hswg: add a minimal README.adoc

Moving the example script from somewhere else.
This commit is contained in:
Přemysl Eric Janouch 2021-06-27 00:00:19 +02:00
parent 04e19f5186
commit 5b432fcc0b
Signed by: p
GPG Key ID: A0420B94F92B9493
2 changed files with 63 additions and 3 deletions

View File

@ -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
~~~~~~~~~~~~~~~~~~~~~~~

62
hswg/README.adoc Normal file
View File

@ -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.