aboutsummaryrefslogtreecommitdiff
path: root/hswg/README.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'hswg/README.adoc')
-rw-r--r--hswg/README.adoc62
1 files changed, 62 insertions, 0 deletions
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/<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.