haven/hswg/README.adoc

63 lines
2.1 KiB
Plaintext
Raw Normal View History

hswg: a static website generator
================================
hswg wraps libasciidoc to make it understand more syntax, namely
two-line/underlined titles, and can be run either as a filter, or as a simple
wiki-like site generator.
Gitea/cgit AsciiDoc processor
-----------------------------
Wrap hswg in the following script to give it a few superpowers:
```
#!/bin/sh
# Make this also work for cgit which, strangely enough, is willing to render
# /anything/ via the /about route, only passing through image/* unchanged.
if [ -z "$GITEA_PREFIX_SRC" ]; then
test "${1%.adoc}" != "$1" || exit 1
cgit_fixups='s/<div class="content">/<div>/'
export GITEA_PREFIX_SRC=. GITEA_PREFIX_RAW=.
fi
# libasciidoc can't be helped in other ways so far, adding support for:
# - the original 'italics' syntax
# - double-line headings (part of haven's hswg which invokes libasciidoc)
# - make links to other documents work, normally an attribute could be used
perl -pe "s|'([-~/\\.\\w]+)'|_\$1_|g;" | hswg 2>/dev/null | \
perl -pe 's|(href=")([^/][^:]*?")|$1$ENV{GITEA_PREFIX_SRC}/$2|;' \
-e 's|(src=")([^/][^:]*?")|$1$ENV{GITEA_PREFIX_RAW}/$2|;' \
-e "$cgit_fixups"
```
Then, to set it up in Gitea, include the following snippet in your _app.ini_:
```
[markup.asciidoc]
ENABLED = true
FILE_EXTENSIONS = .adoc,.asciidoc
RENDER_COMMAND = /usr/local/bin/hswg-gitea
IS_INPUT_FILE = false
```
Similarly for cgit, the following _cgitrc_ snippet might do the job:
```
about-filter=/usr/local/bin/hswg-gitea
readme=:README.adoc
```
If parsing fails for some reason, the contents will be wrapped in HTML verbatim
as plain text.
Wiki mode
---------
The program will read a Go template for the index page from its standard input,
and another template for rendered pages from the path given as its first
argument. The second argument specifies the output filename for the index page,
and the last one is the document directory.
Consult the source code for a list template variables.
All pages will be initially rerendered on startup, and then the directory will
be watched for changes in real time using the inotify API.