~kvik/ugh

97ea5f9d36a15496ab4d58eb9d9a325d9dbc446d — kvik 4 years ago 4ff37fa
Write a first readme iteration
1 files changed, 64 insertions(+), 0 deletions(-)

M README.md
M README.md => README.md +64 -0
@@ 0,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.