diff options
Diffstat (limited to 'README.md')
l---------[-rw-r--r--] | README.md | 142 |
1 files changed, 1 insertions, 141 deletions
diff --git a/README.md b/README.md index c25e751..b23acff 100644..120000 --- a/README.md +++ b/README.md | |||
@@ -1,141 +1 @@ | |||
1 | # UNK | I/index.lh \ No newline at end of file | |
2 | |||
3 | ## a very small static site generator | ||
4 | |||
5 | **UNK** is an experiment in minimalism. | ||
6 | It is a templating static site generator | ||
7 | with an included markup language | ||
8 | that all fits with 1000 bytes. | ||
9 | There are three main scripts: | ||
10 | |||
11 | - **UNK**, a bash script that applies the template | ||
12 | to each page and publishes them to the output dir, | ||
13 | - **LHT**, an awk script that serves as a (very) basic | ||
14 | markup language, and | ||
15 | - **TM**, the default template script for **UNK**. | ||
16 | |||
17 | **UNK** and **LHT** are 250 bytes each, for a total of 500 bytes. | ||
18 | **TM** takes up the remaining 500 bytes | ||
19 | of the target 1000 bytes. | ||
20 | You are, of course, free to make the template file as large | ||
21 | and involved as you like. | ||
22 | |||
23 | # DETAILS | ||
24 | |||
25 | ## unk | ||
26 | |||
27 | **UNK** takes a set of files in a directory, applies a template to them, | ||
28 | and output them into another directory as HTML files ready for a server. | ||
29 | To keep a very small size, **UNK** delegates most file processing to **TM**, | ||
30 | the main template. It delegates by using an idea found in | ||
31 | [shab](https://github.com/zimbatm/shab): | ||
32 | each input file is read as a `heredoc`, which enables | ||
33 | shell interpolation. | ||
34 | So the template, as opposed to the engine, | ||
35 | can do all the heavy-lifting of index generation and navigation and such. | ||
36 | |||
37 | Content goes into the following (hard-coded) directories: | ||
38 | |||
39 | - **I/**, for written (*__i__nput*) content (the pages of the site), | ||
40 | - **S/**, for ***s***tatic content (css, images, etc.), & | ||
41 | - **O/**, for the (*__o__utput*) website, ready for `rsync`ing | ||
42 | to a server. | ||
43 | |||
44 | If there is no **TM** in the directory where **UNK** is run, | ||
45 | one will be created that will simply `cat` the file being processed. | ||
46 | |||
47 | The following variables are made available to **TM**: | ||
48 | |||
49 | - **FN**: the *FileName* (with directories removed) | ||
50 | of the file being processed | ||
51 | - **TT**: the *TiTle* (the first line) of the file | ||
52 | - **BD**: the *BoDy* (the rest) of the file | ||
53 | |||
54 | as well as this function: | ||
55 | |||
56 | - **X**, for *eXpand*: the `shab` stand-in. | ||
57 | It is much simpler than `shab`, and will fail if the template | ||
58 | (or if it nests templates, one of the nested ones) | ||
59 | has a `ZZ` on a line by itself, due to its `heredoc` nature. | ||
60 | |||
61 | and these aliases (though they're more an artefact of saving space | ||
62 | in the script, but they can be used in templates): | ||
63 | |||
64 | - **c**: `cat` | ||
65 | - **q**: `test` | ||
66 | - **e**: `echo` | ||
67 | |||
68 | As mentioned above, templates can be nested. | ||
69 | Simply call another template from **TM** with the **X** function. | ||
70 | |||
71 | ## lht | ||
72 | |||
73 | **LHT** stands for *Less HyperText*, | ||
74 | because that's what you're writing when you're writing it | ||
75 | (though not much less than HTML). | ||
76 | Basically, | ||
77 | blank lines are interpreted as `<p>` tag breaks, | ||
78 | unless the previous source paragraph started with `<` and ended with `>`. | ||
79 | It also has support for three inline spans: | ||
80 | |||
81 | - `*em*` or `_em_` as *em* | ||
82 | - `**strong**` or `__strong__` as **strong** | ||
83 | - `` `code` `` as `code`. | ||
84 | |||
85 | Everything else is just HTML. | ||
86 | |||
87 | **LHT** was inspired, in part, by | ||
88 | [Writing HTML in HTML](http://john.ankarstrom.se/html) by John Ankarstrom, | ||
89 | as well as some other articles I can't think of right now. | ||
90 | I liked the idea, but some tags in HTML are just annoying to write | ||
91 | over and over, and take me out of the flow of writing prose. | ||
92 | So I fixed those few tags. | ||
93 | **The inline tags are definitely subject to change.** | ||
94 | |||
95 | # Why? | ||
96 | |||
97 | I was bored and decided I'd try to write a static site generator | ||
98 | that could fit in a [toot] (500 characters). | ||
99 | I [wrote][1] [a few][2] [of them][3], | ||
100 | making them smaller and smaller each time. | ||
101 | By the end, I was left with a *tiny* script | ||
102 | that delegated almost *all* the work to the template file. | ||
103 | That script became **UNK** in this repo. | ||
104 | |||
105 | [toot]: https://writing.exchange/web/statuses/102333562361891512 | ||
106 | [1]: https://writing.exchange/web/statuses/102334522981990897 | ||
107 | [2]: https://writing.exchange/web/statuses/102334522981990897 | ||
108 | [3]: https://writing.exchange/web/statuses/102339851501562648 | ||
109 | |||
110 | I was feeling pretty high on my horse after writing the tiny SSG, | ||
111 | so I thought, | ||
112 | *[maybe I could try for a tootable Markdown converter next][4]* -- | ||
113 | boy, was I wrong about that. | ||
114 | Markdown is *way* too complicated to fit in 500 bytes. | ||
115 | So I just wrote the Really Important Parts: `<p>` and some inlines. | ||
116 | |||
117 | [4]: https://writing.exchange/@acdw/102339290120562386 | ||
118 | |||
119 | # LEGAL | ||
120 | |||
121 | Copyright © 2019 Case Duckworth <<acdw@acdw.net>>. | ||
122 | |||
123 | This work is free. | ||
124 | You can redistribute it and/or modify it under the terms of | ||
125 | the Do What The Fuck You Want To Public License, Version 2, | ||
126 | as published by Sam Hocevar. | ||
127 | See the LICENSE file for more details. | ||
128 | |||
129 | ## Why this license? | ||
130 | |||
131 | I was going to go with a stricter license like the GPL, | ||
132 | but realized that | ||
133 | |||
134 | 1. this software isn't so important or time-consuming that I need | ||
135 | others to credit me or redistribute the project under the same terms, and | ||
136 | 2. the GPL is *way* too long for a project like this. | ||
137 | It's over 35 times *bigger* than the entirety of this project, | ||
138 | not counting the content or this README. | ||
139 | It would weigh down the entire undertaking. | ||
140 | The WTFPL, by contrast, is a trim 443 characters, | ||
141 | which is right in keeping with the smallness of this project. | ||