Docs Pipeline

How the wiki works

Every push to git@snuffletron:town-records.git triggers an automatic pipeline that rebuilds the live documentation at https://wiki.newingtonamc.com/docs/town-records/.

Pipeline flow

git push snuffletron master
  → post-receive hook fires
    → /home/mkdocs/.tools/sync_docs.sh town-records
      → git archive HEAD doc/ | tar x
        → rsync into /home/mkdocs/town-records/docs/
          → mkdocs build --strict
            → /home/mkdocs/town-records/site/
              → served by nginx at wiki.newingtonamc.com/docs/town-records/

The entire build takes under 1 second.

What gets published

Everything under doc/ in this repository. The mkdocs.yml in doc/ controls navigation and site structure.

Manual rebuild

If the hook fails or you need to test without pushing:

ssh snuffletron 'sudo -u mkdocs /home/mkdocs/.tools/sync_docs.sh town-records'

Adding pages

  1. Create a new .md file in doc/
  2. Add it to the nav section in doc/mkdocs.yml
  3. Push to snuffletron

MkDocs generates anchor IDs from headings by lowercasing and replacing spaces with hyphens. When you change a heading, update any #anchor links that point to it.

Backup

The mkdocs source on snuffletron is backed up automatically. Manual backups:

ssh snuffletron 'cp -r /home/mkdocs/town-records/docs /home/mkdocs/town-records/docs.bak.$(date +%Y%m%d-%H%M)'