About this documentation#

This site is static HTML generated from Markdown by one Python script with no dependencies, and it is written under a rule that every factual claim has to be checkable in the source tree. That rule is the reason each page ends with a "Checked against" line naming the files its claims came from — and the reason those names are links the build verifies rather than a citation style. This page explains the mechanism, the conventions you will notice while reading, and what to do when you find something here that is wrong.

How the site is built#

site/build.py reads Markdown from site/wiki/content/ and writes one directory of HTML per page. It uses the Python 3 standard library and nothing else: no pip install, no npm install, no framework, no content delivery network. The Markdown renderer, the templating, the navigation tree, the search index and the link checker are all in that one file.

The build fails, and names the page, if any of these is true:

1. a page's front matter has no title;
2. an internal link points at a page that does not exist;
3. a #fragment names a heading that is not on the target page;
4. a repo: link names a file that is not in the checkout;
5. a link uses a scheme outside http, https, mailto and the site's own five.

It warns about a missing description, an unknown callout type, an unclosed code fence, and any page whose total weight — HTML, CSS, JavaScript and the one self-hosted typeface — goes over 150 KB.

Anything the renderer does not recognise as Markdown is escaped rather than passed through, so raw HTML written into a page renders as text, and a javascript: or data: link is refused and logged. That is not politeness; it is what lets the site be served under a content security policy of default-src 'none' with 'self' and nothing else.

The "Checked against" line#

Every page in this section ends with a list of repo: links and carries an updated date in its front matter. Together they are a small promise:

• The links are the files the page was written from. Not a bibliography — the actual files someone opened before writing the sentences.
• The build fails if one of them is gone. repo:agent/license.go is checked against the tree on every build, so moving or deleting a cited file breaks the documentation build instead of quietly leaving a claim behind that nothing supports any more.
• The date is when the claims were checked, not when a typo was fixed.

The links resolve to the source forge, which is private. If you cannot open one, that is why: the file name still tells you what to ask for, and everything cited here is either described on the page itself or present on a running router.

The rules these pages are written under#

1. Open the file, then write the sentence. A claim that cannot be pointed at does not go on a page.
2. A feature that does not exist is marked as not built, in words, in a callout that says so — never described in the present tense, never as "coming soon". Everything of that kind is collected on Roadmap.
3. No invented contact details. Where a real address, company name or price does not exist yet, the literal <TODO: owner> is left visible rather than filled in with something plausible. There are no testimonials, no customer names and no team biographies anywhere on this site.
4. Wheelhouse is built on VyOS and says so plainly — in this section, in both footers, with the attribution intact and the source offer linked. See Built on VyOS.
5. Plain, precise, unhurried. The reader is assumed to be an engineer who has been sold something before.

Conventions you will notice#

What this site needs from your browser#

• Reading needs no JavaScript. The navigation tree, the table of contents, the breadcrumbs and every page's content are in the HTML. With scripting off, the navigation stays on the page rather than hiding behind a button that cannot open.
• Search needs it. The index is built at build time and fetched from this host; the query never leaves your browser. Without JavaScript the field is disabled next to a note saying so. The index covers each page's title, headings, description, tags and its first 4000 characters.
• Light and dark follow your system preference, with a toggle that remembers your choice in one browser-local key.
• Nothing loads from anywhere else. One self-hosted typeface, a system monospace stack for code, about 11 KB of hand-written JavaScript and no third-party anything — Privacy.
• Every page carries the commit it was built from in its footer, next to an "Edit this page" link into the forge — which, again, needs a login the reader may not have.

Where else this material lives#

The same facts are maintained in the repository, versioned with the code that makes them true: docs/ for the operator guides, README.md for the honest status, CHANGELOG.md for what each release changed, and PLAN.md for the architecture and the plan. Where this site and one of those disagree, the code decides, and the difference is a bug in whichever document lost.

This site is built from one branch and describes the current tree. There is no version selector and no archive of documentation for older releases — Release history is where a version's changes are recorded.

Reporting an error in a page#

There is no public issue tracker and the support address is not published yet — that gap is described on Support. When there is a route, the most useful report is three lines:

1. the page's URL;
2. the sentence that is wrong;
3. what the code, the file or the router actually does.

The "Checked against" line at the foot of the page is usually the fastest way to show it: if a page cites a file, and that file now says something else, that is the whole report.

See also#

• About Wheelhouse — the rest of this section.
• What is finished, and what is not — the same discipline, applied to the product.
• Contributing to this documentation — how the site is built and how to add a page.

Checked against#

site/build.py · site/README.md · site/IA.md · site/shared/site.json · site/deploy/Caddyfile.snippet · README.md