aboutsummaryrefslogtreecommitdiff
path: root/hswg
diff options
context:
space:
mode:
authorPřemysl Eric Janouch <p@janouch.name>2021-06-27 00:00:19 +0200
committerPřemysl Eric Janouch <p@janouch.name>2021-06-27 00:01:22 +0200
commit5b432fcc0bdee654b225ca2b47cc505e8fb1cf12 (patch)
treec6e9bfd2e881c1a35503bf0ad133ee6ca2635e1c /hswg
parent04e19f51862c7b0395586131a22146c63932d351 (diff)
downloadhaven-5b432fcc0bdee654b225ca2b47cc505e8fb1cf12.tar.gz
haven-5b432fcc0bdee654b225ca2b47cc505e8fb1cf12.tar.xz
haven-5b432fcc0bdee654b225ca2b47cc505e8fb1cf12.zip
hswg: add a minimal README.adoc
Moving the example script from somewhere else.
Diffstat (limited to 'hswg')
-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.