ref: 97ea5f9d36a15496ab4d58eb9d9a325d9dbc446d
parent: 4ff37fa56c63391d780bbc2710894013209bac6b
author: kvik <kvik@a-b.xyz>
date: Tue Jul 28 09:48:37 EDT 2020
Write a first readme iteration
--- a/README.md
+++ b/README.md
@@ -1,0 +1,64 @@
+ugh!
+====
+
+ugh! is a website generator.
+
+Theory of operation
+-------------------
+
+### Structure
+
+The website source comprises tree structure and page content files
+maintained under top-level directory `data/`.
+
+Top-level mk(1) targets drive the compilation of website source into
+output directory `public/`. Compilation process can be controlled
+through configuration files in the `cfg/` directory.
+
+The website template is defined by files in the `templates/` directory.
+The templating engine is rc(1) heredocs—it is rather limited but should
+be understandable.
+The default template tries to load `public/css/style.css` stylesheet,
+which doesn't exist by default.
+
+### Transformation rules
+
+Currently supported content files are markdown, html, and raw text.
+
+Copies of the source files with `.html`, `.txt`, and `.md` extensions
+are included verbatim in the output directory.
+
+Source files with `.md` extension are filtered through a `bin/mdtohtml`
+program to produce an HTML body, which is expanded into a page template
+and stored in a matching `.html` output file.
+
+### Filters
+
+Helpers like `bin/mdtohtml` may be modified or replaced by users to
+select a different underlying filter program, change the configuration,
+do some advanced processing, and so on.
+
+Install
+-------
+
+Copy this directory to a suitable place and make sure the dependencies
+are met.
+
+### Dependencies
+
+9front version of `rc(1)` and `mk(1)` are the core dependencies.
+**NB** Other versions of rc are guaranteed not to work.
+
+The default markdown filter `bin/mdtohtml` depends on the
+[discount(1)](https://github.com/Orc/discount) markdown processor.
+You can easily change it to something else.
+
+Use
+---
+
+Create some content files in the `data/` directory and run:
+
+ mk
+
+in the top-level directory. This will generate the website files
+in the `public/` directory. Publish this whichever way you like.