186 lines
8.6 KiB
HTML
186 lines
8.6 KiB
HTML
<!DOCTYPE html>
|
|
<meta charset=utf-8>
|
|
<title>UNK</title>
|
|
<style>body{max-width:70ch;padding:1em;margin:auto}
|
|
#toc{background:pink;padding:1em;display:block}</style>
|
|
<h1><h1>UNK</h1></h1>
|
|
<h2>a very small static site generator</h2>
|
|
<p><strong>UNK</strong> is an experiment in minimalism.
|
|
It is a templating static site generator
|
|
with an included markup language
|
|
that all fits within 1000 bytes.
|
|
There are three main scripts:</p>
|
|
<ul>
|
|
<li><strong>UNK</strong> (253 bytes), a POSIX-sh script that applies
|
|
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>
|
|
<li><strong>TM</strong> (502 bytes),
|
|
the default template script for <strong>UNK</strong>.</li>
|
|
</ul>
|
|
<p>You are, of course, free to make the template file as large
|
|
and involved as you like, but it's pretty good already:</p>
|
|
<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>
|
|
<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>
|
|
<p>To install <strong>UNK</strong>, simply clone this repo and put it where you want it.
|
|
The default <strong>TM</strong> needs <strong>LHT</strong> to be in the same directory as it,
|
|
so keep that in mind.</p>
|
|
<p>To run <strong>UNK</strong>, just <code>cd</code> into your cloned repo and run <code>./unk</code>.
|
|
It's just a POSIX shell script.</p>
|
|
<h1>DETAILS</h1>
|
|
<h2>unk</h2>
|
|
<p><strong>UNK</strong> 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.
|
|
To keep a very small size, <strong>UNK</strong> delegates most file processing to <strong>TM</strong>,
|
|
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 <code>heredoc</code>, 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.</p>
|
|
<p>Content goes into the following (hard-coded) directories:</p>
|
|
<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>
|
|
<p>If there is no <strong>TM</strong> in the directory where <strong>UNK</strong> is run,
|
|
one will be created that will simply <code>cat</code> the file being processed.</p>
|
|
<p>The following variable is made available to <strong>TM</strong>:</p>
|
|
<ul>
|
|
<li><strong>F</strong>: the <em>File</em> name passed to
|
|
<strong>TM</strong></li>
|
|
<li><strong>N</strong>: the <em>fileName</em>
|
|
(with directories removed) of the file being processed</li>
|
|
</ul>
|
|
<p>as well as these functions:</p>
|
|
<ul>
|
|
<li><strong>X</strong>, for <em>eXpand</em>:
|
|
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)
|
|
has a <code>ZZ</code> on a line by itself,
|
|
due to its <code>heredoc</code> nature.</li>
|
|
<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 <em>but</em> the first of the current file.</li>
|
|
</ul>
|
|
<p>and these aliases (though they're more an artefact of saving space
|
|
in the script, but they can be used in templates):</p>
|
|
<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>
|
|
<p>As mentioned above, templates can be nested.
|
|
Simply call another template from <strong>TM</strong> with the <strong>X</strong> function.</p>
|
|
<h2>lht</h2>
|
|
<p><strong>LHT</strong> stands for <em>Less HyperText</em>,
|
|
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:</p>
|
|
<ul>
|
|
<li><code>*em*</code>
|
|
as <em>em</em></li>
|
|
<li><code>__strong__</code>
|
|
as <strong>strong</strong></li>
|
|
<li><code>`code`</code> as <code>code</code></li>
|
|
</ul>
|
|
<p>Everything else is just HTML.
|
|
This means that a valid <code>.lh</code> file is <em>almost</em> a valid <code>.md</code> file,
|
|
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.
|
|
This file, for example, is both <code>index.lh</code> and <code>README.md</code>
|
|
(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.).</p>
|
|
<p><strong>LHT</strong> 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.
|
|
<strong>The inline tags are definitely subject to change.</strong></p>
|
|
<h1>Why?</h1>
|
|
<p>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 <em>tiny</em> script
|
|
that delegated almost <em>all</em> the work to the template file.
|
|
That script became <strong>UNK</strong> in this repo.</p>
|
|
<p>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
|
|
I could try for a tootable Markdown converter next</a></em> —
|
|
boy, was I wrong about that.
|
|
Markdown is <em>way</em> too complicated to fit in 500 bytes.
|
|
So I just wrote the Really Important Parts: <code><p></code>
|
|
and some inlines.</p>
|
|
<h1>LEGAL</h1>
|
|
<p>Copyright © 2019 Case Duckworth
|
|
<<a href="mailto:acdw@acdw.net">acdw@acdw.net</a>>.</p>
|
|
<p>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.
|
|
See the <a href="https://git.sr.ht/~acdw/unk/tree/master/LICENSE">LICENSE</a>
|
|
file for more details.</p>
|
|
<h2>Why this license?</h2>
|
|
<p>I was going to go with a stricter license like the GPL,
|
|
but realized that</p>
|
|
<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>
|
|
<h1>CONTRIBUTING</h1>
|
|
<p>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'" /></p>
|
|
<ul id=toc>Pages
|
|
<li><a href='carpe-diem.htm'>Carpe diem</a></li>
|
|
<li><a href='rosa-rosa-rosam.htm'>Rosa Rosa Rosam</a></li>
|
|
<li><a href='spqr.htm'>S.P.Q.R.</a></li>
|
|
<li><a href='tu-quoque.htm'>Tu quoque</a></li>
|
|
</ul>
|
|
<p id=ft>© 2019</p>
|
|
|