Site Architecture

The site follows Hugo's separation between content, presentation, static assets, configuration, generated output, and the optional search service.

Repository structure

.
├── content/
│   ├── _index.org
│   ├── about/
│   ├── research/
│   ├── engineering/
│   ├── software/
│   ├── projects/
│   ├── debian/
│   ├── digital-rights/
│   ├── politics/
│   └── website/
├── layouts/
│   ├── _default/
│   └── home.html
├── scripts/
│   ├── build_search_index.py
│   ├── check_site.py
│   └── render_math.py
├── server/
│   └── search.cgi
├── static/
│   ├── css/
│   └── files/
├── hugo.toml
└── Makefile

Content model

Org Mode remains the authoring format.

A section is represented by a directory containing an _index.org file. For example:

content/research/_index.org
content/research/electrochemical-noise.org
content/research/pem-fuel-cells.org

The hierarchy is therefore represented by the filesystem instead of numeric prefixes embedded in visible page titles.

Ordering inside a section is controlled with metadata such as:

#+title: PEMFC Multiphysics Modelling
#+weight: 40

This keeps titles semantic while still allowing deterministic navigation.

Layouts

Hugo templates define the common HTML structure.

The base template contains the document shell, stylesheet, horizontal navigation, content area, and footer. Section and single-page templates only define the part that differs.

Shared interface elements are defined once in the common templates rather than duplicated in individual Org source files.

This keeps the generated HTML consistent while leaving content files focused on the actual page material.

Static files

Files placed under static/ are copied directly to the generated site.

This repository keeps the stylesheet, PDF documents, robots.txt, and the search-engine verification file there. No JavaScript is shipped to visitors.

TeX fragments are rendered to SVG during the production build by scripts/render_math.py using LaTeX and dvisvgm. The generated pages therefore contain static SVG mathematics and require no client-side MathJax.

Generated output

Running Hugo creates public/.

The public/ directory is a build artefact, not source material, and is excluded from Git.

nginx serves this generated directory after deployment.

Search

Reading the site itself requires only static files.

Full-text search is an optional server-side component. During the build, scripts/build_search_index.py extracts text from the generated HTML and creates a SQLite FTS5 index. The server/search.cgi CGI program queries that index in read-only mode.

The search form itself is plain HTML using a GET request to the CGI endpoint. It does not require JavaScript.

The site does not provide a manual theme selector. Colour mode follows the browser or operating-system preference through CSS color-scheme, so no JavaScript, cookie, or server-side theme state is required.

The search component is therefore separate from page rendering and can fail or be disabled without preventing access to the static site.

Sitemap and section indexes

Hugo derives site structure from content rather than from a custom title parser. Section pages can enumerate their children through templates, and Hugo can generate XML sitemap output from the same page model.

The important architectural change is therefore:

old: title conventions -> custom Elisp parsing -> navigation
new: content hierarchy + metadata -> Hugo page model -> navigation