Publishing Workflow

Pages are edited as Org Mode files in content/, normally from Emacs.

The source remains ordinary text suitable for Git diffs, review, search, and long-term archival.

During editing:

make serve

which performs a complete production build and then runs:

python3 -m http.server --directory public 1313

This previews exactly the generated files, including statically rendered mathematics. The site can then be inspected at:

http://localhost:1313/

The development server is only a local preview tool. It is not part of the production architecture.

A production build is generated with:

make build

The Makefile runs Hugo, converts TeX fragments in the generated HTML to static SVG with LaTeX and dvisvgm, and then builds the site's SQLite FTS5 search index.

The generated site and search database are written to public/. No JavaScript is required or shipped in generated pages.

Before deployment:

make check

This performs a fresh production build and then validates the generated site. The automated checks currently cover:

• Python syntax for build and CGI utilities;
• presence of index.html, robots.txt, sitemap.xml, and search.db;
• broken internal links and missing local assets;
• any JavaScript at all in generated HTML;
• unexpected externally hosted stylesheets.

The checks operate on the generated public/ tree, i.e. the same files that nginx will serve. Manual inspection remains useful for rendering, equations, responsive layout, navigation ordering, and light/dark appearance.

Deployment is performed with rsync through the Makefile:

make deploy

The deploy target depends on check. A failed build or validation therefore stops deployment before rsync is invoked.

The Makefile provides default values for the SSH destination and production directory:

REMOTE ?= fgm@m710s
REMOTE_DIR ?= /srv/www/html

Both variables are deliberately overridable, for example:

make deploy REMOTE=server REMOTE_DIR=/srv/www/site

The deployment excludes the OpenPGP WKD tree so that publishing the website does not delete independently managed WKD files.

Source history is kept in Git. A previous revision can therefore be rebuilt and redeployed if required.

For a small static website this is preferable to maintaining mutable content inside a production application or database.

Recent Hugo releases deny Org content by default because Org export constructs can emit raw HTML or JavaScript.

This repository explicitly permits text/org in hugo.toml because the Org sources are locally authored and reviewed. Content from untrusted contributors should not be accepted into this pipeline without review.