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 page cites a file that is not in this checkout. Those are errors rather than warnings.

What a page owes its reader#

1. Every factual claim is checkable in the code. Open the file, then write the sentence. Name the file in the page's checked front matter so the build fails when it moves. The list is verified on every build and never rendered. Only the development section links into the source with repo:, where a reader has come to read it.
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, say the true thing in plain words — "pricing is not published yet", "there is no published support address" — and record the outstanding decision in site/OWNER-DECISIONS.md, which is not published. Never leave a template marker on a page a customer reads.
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.