2019-07-01 17:42:31 +00:00
|
|
|
<h1>UNK</h1>
|
|
|
|
|
|
|
|
<h2>a very small static site generator</h2>
|
|
|
|
|
|
|
|
__UNK__ is an experiment in minimalism.
|
|
|
|
It is a templating static site generator
|
|
|
|
with an included markup language
|
2019-07-01 22:26:46 +00:00
|
|
|
that all fits within 1000 bytes.
|
2019-07-01 17:42:31 +00:00
|
|
|
There are three main scripts:
|
|
|
|
|
|
|
|
<ul>
|
2021-01-30 21:33:58 +00:00
|
|
|
<li><strong>UNK</strong> (239 bytes), a POSIX-sh script that applies
|
2019-07-01 21:54:16 +00:00
|
|
|
the template to each page and publishes them to the output dir,</li>
|
|
|
|
<li><strong>LHT</strong> (241 bytes), an awk script that serves as
|
|
|
|
a (very) basic markup language, and</li>
|
2021-01-30 21:33:58 +00:00
|
|
|
<li><strong>L</strong> (502 bytes),
|
2019-07-01 17:42:31 +00:00
|
|
|
the default template script for <strong>UNK</strong>.</li>
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
You are, of course, free to make the template file as large
|
2019-07-01 22:41:01 +00:00
|
|
|
and involved as you like, but it's pretty good already:
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
<li>it has a plain default CSS
|
|
|
|
(based on <a href="https://jrl.ninja/etc/1/">this article</a>),
|
|
|
|
or will use <code>S/s.css</code> if it exists</li>
|
|
|
|
<li>it automatically adds a list of posts to the index page,
|
|
|
|
or a <em.return</em> link to other pages</li>
|
|
|
|
<li>it cleans up the first line of the input file and makes it a
|
|
|
|
<code><title></code>, and a <code><h1></code>
|
|
|
|
in the generated HTML</li>
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
<h1>INSTALLING & RUNNING</h1>
|
|
|
|
|
2019-07-02 01:16:30 +00:00
|
|
|
<a href="https://git.sr.ht/~acdw/unk"><strong>OFFICIAL REPO</strong></a> //
|
|
|
|
<a href="https://github.com/duckwork/unk"><strong>GITHUB MIRROR</strong></a>
|
|
|
|
|
2019-07-01 22:41:01 +00:00
|
|
|
To install __UNK__, simply clone this repo and put it where you want it.
|
2021-01-30 21:33:58 +00:00
|
|
|
The default __L__ needs __LHT__ to be in the same directory as it,
|
2019-07-01 22:41:01 +00:00
|
|
|
so keep that in mind.
|
|
|
|
|
|
|
|
To run __UNK__, just `cd` into your cloned repo and run `./unk`.
|
|
|
|
It's just a POSIX shell script.
|
2019-07-01 17:42:31 +00:00
|
|
|
|
|
|
|
<h1>DETAILS</h1>
|
|
|
|
|
|
|
|
<h2>unk</h2>
|
|
|
|
|
|
|
|
__UNK__ takes a set of files in a directory, applies a template to them,
|
|
|
|
and output them into another directory as HTML files ready for a server.
|
2021-01-30 21:33:58 +00:00
|
|
|
To keep a very small size, __UNK__ delegates most file processing to __L__,
|
2019-07-01 17:42:31 +00:00
|
|
|
the main template. It delegates by using an idea found in
|
|
|
|
<a href="https://github.com/zimbatm/shab">shab</a>:
|
|
|
|
each input file is read as a `heredoc`, which enables
|
|
|
|
shell interpolation.
|
|
|
|
So the template, as opposed to the engine,
|
|
|
|
can do all the heavy-lifting of index generation and navigation and such.
|
|
|
|
|
|
|
|
Content goes into the following (hard-coded) directories:
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
<li><strong>I/</strong>,
|
|
|
|
for written (<em><strong>I</strong>nput</em>) content
|
|
|
|
(the pages of the site),</li>
|
|
|
|
<li><strong>S/</strong>, for <em><strong>S</strong>tatic</em> content
|
|
|
|
(css, images, etc.), &</li>
|
|
|
|
<li><strong>O/</strong>, for the (<em><strong>O</strong>utput</em>)
|
|
|
|
website, ready for <code>rsync</code>ing to a server.</li>
|
|
|
|
</ul>
|
|
|
|
|
2021-01-30 21:33:58 +00:00
|
|
|
If there is no __L__ in the directory where __UNK__ is run,
|
2019-07-01 17:42:31 +00:00
|
|
|
one will be created that will simply `cat` the file being processed.
|
|
|
|
|
2021-01-30 21:33:58 +00:00
|
|
|
The following variable is made available to __L__:
|
2019-07-01 17:42:31 +00:00
|
|
|
|
|
|
|
<ul>
|
2019-07-01 22:31:25 +00:00
|
|
|
<li><strong>F</strong>: the <em>File</em> name passed to
|
2021-01-30 21:33:58 +00:00
|
|
|
<strong>L</strong></li>
|
2019-07-01 22:31:25 +00:00
|
|
|
<li><strong>N</strong>: the <em>fileName</em>
|
2019-07-01 17:42:31 +00:00
|
|
|
(with directories removed) of the file being processed</li>
|
|
|
|
</ul>
|
|
|
|
|
2019-07-01 21:54:16 +00:00
|
|
|
as well as these functions:
|
2019-07-01 17:42:31 +00:00
|
|
|
|
|
|
|
<ul>
|
2019-07-01 17:46:38 +00:00
|
|
|
<li><strong>X</strong>, for <em>eXpand</em>:
|
2019-07-01 17:42:31 +00:00
|
|
|
the <code>shab</code> stand-in.
|
|
|
|
It is much simpler than <code>shab</code>,
|
|
|
|
and will fail if the template
|
|
|
|
(or if it nests templates, one of the nested ones)
|
2021-01-30 21:33:58 +00:00
|
|
|
has a <code>^D</code> on a line by itself,
|
2019-07-01 17:42:31 +00:00
|
|
|
due to its <code>heredoc</code> nature.</li>
|
2019-07-01 21:54:16 +00:00
|
|
|
<li><strong>T</strong>, for <em>Title</em>:
|
|
|
|
it'll return the first line of the current file.</li>
|
|
|
|
<li><strong>B</strong>, for <em>Body</em>:
|
|
|
|
it'll return all lines *but* the first of the current file.</li>
|
2019-07-01 17:42:31 +00:00
|
|
|
</ul>
|
|
|
|
|
|
|
|
and these aliases (though they're more an artefact of saving space
|
|
|
|
in the script, but they can be used in templates):
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
<li><strong>c</strong>: <code>cat</code></li>
|
|
|
|
<li><strong>q</strong>: <code>test</code></li>
|
|
|
|
<li><strong>e</strong>: <code>echo</code></li>
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
As mentioned above, templates can be nested.
|
2021-01-30 21:33:58 +00:00
|
|
|
Simply call another template from __L__ with the __X__ function.
|
2019-07-01 17:42:31 +00:00
|
|
|
|
|
|
|
<h2>lht</h2>
|
|
|
|
|
|
|
|
__LHT__ stands for *Less HyperText*,
|
|
|
|
because that's what you're writing when you're writing it
|
|
|
|
(though not much less than HTML).
|
|
|
|
Basically,
|
|
|
|
blank lines are interpreted as <code><p></code> tag breaks,
|
|
|
|
unless the previous source paragraph started with
|
|
|
|
<code><</code> and ended with <code>></code>.
|
|
|
|
It also has support for three inline spans:
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
<li><code>*em*</code>
|
|
|
|
as <em>em</em></li>
|
|
|
|
<li><code>__strong__</code>
|
|
|
|
as <strong>strong</strong></li>
|
2019-07-01 18:03:05 +00:00
|
|
|
<li><code>`code`</code> as <code>code</code></li>
|
2019-07-01 17:42:31 +00:00
|
|
|
</ul>
|
|
|
|
|
|
|
|
Everything else is just HTML.
|
2019-07-01 22:33:41 +00:00
|
|
|
This means that a valid `.lh` file is *almost* a valid `.md` file,
|
2019-07-01 17:42:31 +00:00
|
|
|
except where it nests HTML and Markdown
|
|
|
|
(so it's not really, but you can run it through Markdown in a pinch
|
|
|
|
and get the basic idea across.
|
2019-07-01 22:33:41 +00:00
|
|
|
This file, for example, is both `index.lh` and `README.md`
|
2019-07-01 17:42:31 +00:00
|
|
|
(they're just symlinked to each other),
|
|
|
|
so it's got some weirdness to keep things compatible between Markdown and LHT.
|
|
|
|
But if you're just writing for LHT, it can be much simpler.).
|
|
|
|
|
|
|
|
__LHT__ was inspired, in part, by
|
|
|
|
<a href="http://john.ankarstrom.se/html">Writing HTML in HTML</a>
|
|
|
|
by John Ankarstrom,
|
|
|
|
as well as some other articles I can't think of right now.
|
|
|
|
I liked the idea, but some tags in HTML are just annoying to write
|
|
|
|
over and over, and take me out of the flow of writing prose.
|
|
|
|
So I fixed those few tags.
|
|
|
|
__The inline tags are definitely subject to change.__
|
|
|
|
|
|
|
|
<h1>Why?</h1>
|
|
|
|
|
|
|
|
I was bored and decided I'd try to write a static site generator
|
|
|
|
that could fit in a
|
|
|
|
<a href="https://writing.exchange/web/statuses/102333562361891512">toot</a>
|
|
|
|
(500 characters).
|
|
|
|
I
|
|
|
|
<a href="https://writing.exchange/web/statuses/102334522981990897">wrote</a>
|
|
|
|
<a href="https://writing.exchange/web/statuses/102334522981990897">a few</a>
|
|
|
|
<a href="https://writing.exchange/web/statuses/102339851501562648">of them</a>,
|
|
|
|
making them smaller and smaller each time.
|
|
|
|
By the end, I was left with a *tiny* script
|
|
|
|
that delegated almost *all* the work to the template file.
|
|
|
|
That script became __UNK__ in this repo.
|
|
|
|
|
|
|
|
I was feeling pretty high on my horse after writing the tiny SSG,
|
|
|
|
so I thought,
|
|
|
|
<em><a href="https://writing.exchange/@acdw/102339290120562386">maybe
|
2019-07-01 21:46:18 +00:00
|
|
|
I could try for a tootable Markdown converter next</a></em> —
|
2019-07-01 17:42:31 +00:00
|
|
|
boy, was I wrong about that.
|
|
|
|
Markdown is *way* too complicated to fit in 500 bytes.
|
|
|
|
So I just wrote the Really Important Parts: <code><p></code>
|
|
|
|
and some inlines.
|
|
|
|
|
|
|
|
<h1>LEGAL</h1>
|
|
|
|
|
|
|
|
Copyright © 2019 Case Duckworth
|
2019-07-01 22:24:54 +00:00
|
|
|
<<a href="mailto:acdw@acdw.net">acdw@acdw.net</a>>.
|
2019-07-01 17:42:31 +00:00
|
|
|
|
|
|
|
This work is free.
|
|
|
|
You can redistribute it and/or modify it under the terms of
|
|
|
|
the Do What The Fuck You Want To Public License, Version 2,
|
|
|
|
as published by Sam Hocevar.
|
2019-07-01 22:11:29 +00:00
|
|
|
See the <a href="https://git.sr.ht/~acdw/unk/tree/master/LICENSE">LICENSE</a>
|
|
|
|
file for more details.
|
2019-07-01 17:42:31 +00:00
|
|
|
|
|
|
|
<h2>Why this license?</h2>
|
|
|
|
|
|
|
|
I was going to go with a stricter license like the GPL,
|
|
|
|
but realized that
|
|
|
|
|
|
|
|
<ol>
|
|
|
|
<li>this software isn't so important or time-consuming that I need
|
|
|
|
others to credit me or redistribute the project under the same terms,
|
|
|
|
and</li>
|
|
|
|
<li>the GPL is <em>way</em> too long for a project like this.
|
|
|
|
It's over 35 times <em>bigger</em> than the entirety of this project,
|
|
|
|
not counting the content or this README.
|
|
|
|
It would weigh down the entire undertaking.
|
|
|
|
The WTFPL, by contrast, is a trim 443 characters,
|
|
|
|
which is right in keeping with the smallness of this project.</li>
|
|
|
|
</ol>
|
2019-07-02 01:06:43 +00:00
|
|
|
|
|
|
|
<h1>CONTRIBUTING</h1>
|
|
|
|
|
|
|
|
To contribute to this project,
|
|
|
|
head over to <a href="https://github.com/duckwork/unk">its GitHub mirror</a>
|
|
|
|
and send me a pull request or issue.
|
|
|
|
One of these days, I'm sure I'll figure out sr.ht's mailing lists,
|
|
|
|
<img src="S/not-this-day.gif" style="display:block;margin:1em auto;"
|
|
|
|
alt="Meme of Aragorn saying, 'But it is not this day'" />
|