diff --git a/README.adoc b/README.adoc index 982c287..9f43933 100644 --- a/README.adoc +++ b/README.adoc @@ -96,9 +96,7 @@ Only UTF8_STRING-convertible selections are synchronized. hswg -- static website generator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Wraps libasciidoc to make it understand more syntax, namely two-line/underlined -titles, and can be run either as an AsciiDoc processor for my Gitea, or as -a trivial wiki-like site generator. +link:hswg/README.adoc[See hswg's README for details.] ht -- terminal emulator ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/hswg/README.adoc b/hswg/README.adoc new file mode 100644 index 0000000..3cefe5b --- /dev/null +++ b/hswg/README.adoc @@ -0,0 +1,62 @@ +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/
/
/' + 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.