# Trac Wiki converted to Pelican Markdown

The Trac Wiki that used to hold this site has been converted to a
wiki-like setup using git, Markdown, Pelican, and m.css.

* [git repository behind this Wiki](https://git.cryptech.is/wiki).
* [Pelican documentation](https://docs.getpelican.com/en/stable/).
* [m.css documentation](https://mcss.mosra.cz/themes/pelican/).

The git repository is configured to generate the web content from the
Markdown automatically upon receiving a `git push`.

[linkchecker](https://linkcheck.github.io/linkchecker/) may also be
useful in validating the generated content.

The `Makefile` in this directory makes it easy to test out changes to
the content before pushing them, eg:

```
make all check server
```

will generate the content, run the result through `linkchecker`, then
start up a web server on the name and port specified in the Makefile
(which you can override with the `HTTP_HOST` and `HTTP_PORT`
variables) to let you browse the result.  Feel free to experiment on
your own copy: there are almost certainly things we could do better
within the Pelican framework, maybe you'll figure them out for us.

The upstream repository is configured to run Pelican automatically on
push and install the result, and to refuse the push if something fails
to compile.  It is of course possible to mess things up in ways that
won't cause compilation to fail, so don't do that. :)

As with all Cryptech git repositories, all commits to this repository
must be signed by a known key.

For completeness, here's how this hooks into git: hang something like
the following script off the upstream repository's `update` hook:

```
#!/bin/sh -

set -xe

ref="$1"
oldrev="$2"
newrev="$3"

branch=refs/heads/master
repo=/some/where/safe.git
work=/some/where/else
dest=/some/where/visible

if test "$ref" = "$branch"
then
    export CRYPTECH_WIKI_PRODUCTION_BUILD=true
    cd $work
    git --git-dir $repo --work-tree $work checkout --force $newrev
    git --git-dir $repo --work-tree $work submodule update --init
    pelican --output website --settings pelicanconf.py --fatal errors content
    chmod -R a+rX $work
    rsync -a --delete website/ $dest/
fi
```

Setting `--git-dir` is *probably* unnecessary, since the hook will
inherit the `$GIT_DIR` environment variable, but it's also harmless.
`$CRYPTECH_WIKI_PRODUCTION_BUILD` allows our `pelicanconf.py` to
default to developer settings while automatically using production
settings when built using the git hook.