Contributing#

This site is generated by site/build.py, a static site generator written against the Python 3 standard library and nothing else. There is no npm install and no pip install, because the product builds its .deb without either and CI will not grow a dependency for a website.

Building it#

python3 site/build.py            # both sites into site/dist/
python3 site/build.py --clean    # remove site/dist first
python3 site/build.py --strict   # warnings become errors
python3 site/build.py --serve wiki --port 8080

The build exits non-zero if a page has no title, if an internal link points at a page that does not exist, if a #fragment names a heading that is not on the target page, or if a repo: link names a file that is not in this checkout. Those are errors rather than warnings on purpose. A documentation site that links to a page that does not exist is a documentation site that has started lying, and the difference between the two is smaller than it looks.

What a page owes its reader#

1. Every factual claim is checkable in the code. Open the file, then write the sentence. Link to the file with repo: so the reader can do the same and so the build fails when the file moves.
2. A missing feature is either absent from the page or under a :::roadmap block that says plainly it is not built. There is no third option, and especially not the present tense.
3. No invented details. No email addresses, no phone numbers, no benchmarks nobody ran, no prices nobody has set. Where a real detail is missing, write <TODO: owner> and leave it visible.
4. Plain sentences. The reader is a network engineer who has been lied to by marketing before. Technical accuracy is the persuasion.

Adding a page#

Put a Markdown file under site/wiki/content/. The path becomes the URL: site/wiki/content/manual/firewall.md is served at /manual/firewall/, and manual/index.md is served at /manual/, which also gives the manual branch of the navigation tree its title and its position.

Every page opens with front matter:

---
title: Firewall
description: Zone policy, rule sets, and the nftables they become.
order: 20
tags: [firewall, nftables]
---

# Firewall

The page template documents every front-matter key and every Markdown construct the renderer supports, and is itself rendered by that renderer, so it cannot describe a feature that does not work.