Writing Pages Guide

Writing Pages Guide

Phase 3 craft: the anatomy every page must have, the filename rule that decides whether links live or die, how to use GitHub's 2026 rendering features (alerts, mermaid, tables) without shipping broken markup, the house style the auditor enforces, and the fix_toc loop that keeps anchors honest. Examples are taken from the kit's own templates and from pages of this wiki, all of which passed qa_wiki.py --strict with zero errors.

Contents

• Scaffold first, write second
• The filename rule
• Page anatomy in GFM (2026 conventions)
  • GitHub Alerts
  • Mermaid
  • Tables
  • Code fences
  • Wiki-links and anchors
• House style (auditor-enforced)
• The fill loop
• Home, sidebar and footer
• See also

---

Scaffold first, write second

python3 scaffold/new_page.py workspace/wiki/OWNER.REPO.wiki --init \
    --project "SUBJECT" --repo-url https://github.com/OWNER/REPO \
    --version X.Y.Z --commit abc1234 --license MIT \
    --progress workspace/PROGRESS.json

The skeleton the scaffold emits is QA-clean by construction — verified across three different page lists including the degenerate one-page case (T8). Each stub carries the five structural obligations, so writing is about content only:

Slot	Obligation
# Title	exactly one H1 per page
lead paragraph	≥40 characters of prose directly under the H1 (alerts, tables, lists do not count)
## Contents	list block; anchors are rebuilt by fix_toc.py, never hand-written
body	logical H2/H3 sections
## See also	cross-links; the navigation contract of every page

Write the two hardest pages first, while the research is fresh — in the reference run and in this one, the security page and the big reference matrices. Everything after them reuses tables and phrasings you got right once.

The filename rule

GitHub maps spaces in a wiki filename to hyphens in the URL and resolves [[Page Name]] against that mapping:

File in the wiki repo	URL	[[Security Hardening Guide]]
Security Hardening Guide.md	/wiki/Security-Hardening-Guide	resolves
Security-Hardening-Guide.md	/wiki/Security-Hardening-Guide	dead

So: name files with spaces, link with the same spaces, and never "fix" a dead link by renaming the file to hyphens. Underscores in a filename become spaces in the displayed title — avoid them except for _Sidebar.md and _Footer.md, which keep their underscores because they are special: GitHub renders them on every page and does not list them. The auditor's link error even prints the hint when it sees the hyphenated twin of a missing page.

Page anatomy in GFM (2026 conventions)

GitHub Alerts

Five types, exactly: NOTE, TIP, IMPORTANT, WARNING, CAUTION. Anything else renders as a plain blockquote with the literal [!TYPE] visible — the auditor rejects it.

> [!IMPORTANT]
> The one rule: a claim enters the wiki only if it is traced to a source
> line, or reproduced by running the software.

> [!CAUTION]
> Probe batteries fire attack payloads. Only run them against software you
> are authorized to test.

Use alerts for stakes, not for emphasis decoration: a security property, a hard requirement, a limitation that changes a decision. The reference run used 154 alerts across 73k words — roughly one per 475 words.

Mermaid

Three rules keep diagrams rendering on GitHub (PITFALLS C6; all auditor-enforced):

1. & must be written & inside labels, including quoted ones (bare & in an edge label is an error; inside a quoted label, a warning).
2. Any label containing special characters — parentheses, brackets, braces, colons, regex backslashes — must be wrapped in double quotes: B{"Array value?<br/>(INI key[] syntax)"} passes; B{Array value? (key[] syntax)} is a parse error. The cylinder shape [(...)] and circle ((...)) are legitimate and exempt from the inner-bracket check.
3. Prefer prose over clever notation in labels: force flag preserved beats a parenthesised symbol soup.

flowchart LR
    R["research/facts.json"] --> W["write pages"]
    W --> F["qa/fix_toc.py<br/>rebuild Contents"]
    F --> Q{"qa_wiki.py --strict<br/>0 errors?"}
    Q -- "no" --> W
    Q -- "yes" --> P["publish/publish.sh"]

Loading

Balance rules the auditor applies per diagram kind: in flowcharts, every subgraph needs an end; in sequence diagrams, end closes alt/opt/loop/par blocks instead, so the counting is kind-aware. Brackets and quotes must balance everywhere except bracket-balance in sequenceDiagram.

Tables

Tables are the house format for: parameters and flags (option → default → effect), configuration surfaces, error codes and exact strings, compatibility and feature-support matrices, comparison pages, and per-test evidence. The reference run shipped 1,687 table rows across 22 files; this wiki averages ~40 rows per filled page. Keep cells short; move prose out of the table into the paragraph above it.

Code fences

Every command in a fenced block with a language tag, copy-pasteable, with sample output where useful (output blocks tagged text or console so the shell checker skips transcripts honestly). Two nesting rules:

• An example that itself contains a fence needs a longer outer fence — four backticks around a block that shows three. With three on the outside, the inner fence closes the block early and the rest of the page renders as garbage. This bug shipped once in the reference run and was caught only by the auditor (PITFALLS C7).
• Every bash/sh block is syntax-checked with bash -n; every python block must compile(). A snippet you would not dare run, do not fence as runnable.

Wiki-links and anchors

Cross-page: [[Page Name]], optionally [[Page Name#anchor|label]]. In-page: [label](#slug) where the slug follows GitHub's algorithm — lowercase; strip everything except alphanumerics, spaces, hyphens, underscores; spaces to hyphens; do not collapse repeated hyphens (an em dash between words yields a double hyphen, e.g. #step-6--read-mdini); duplicates dedupe with -1, -2. Never hand-write these: write the page, then run fix_toc.py, then let the auditor verify. A [[1,2]]-style citation in prose becomes a live link to a non-existent page — wrap such examples in backticks.

House style (auditor-enforced)

Rule	Enforcement
Factual tone; state what it does, not that it is great	20 filler regexes → error (exemptable for domain terms)
No decorative emoji	emoji outside code → warning; acceptable only as data (a documented character mapping or a verbatim UI glyph — wrap the glyph in backticks)
One consistent vocabulary	terms.json canonical counts + avoid errors
No unverified claims	ban.json errors + the one-rule doctrine + sources.md §D
Every page navigable	sidebar coverage check + ## See also requirement
Claims carry provenance where valuable	facts.json source discipline; [tested] markers in research notes; test IDs cited in pages

Style notes that are not enforced but keep 20 pages coherent: British or American spelling consistently (this wiki: American); numbers with units (0.46 s, 73,013 words); file paths in backticks; tool names as written in the tree (qa_wiki.py, not "the QA tool" in instructions); tables over bullet lists when rows have ≥3 attributes.

The fill loop

For each page:

1. Replace the lead-paragraph slot with 1–3 sentences: what the page covers and when a reader needs it.
2. Fill sections from research/ — not from memory. When a fact matters, cite it: a file:line, a test ID, or a doc source.
3. Add devices where they earn their place: a mermaid diagram for structure/process, an alert for stakes, tables for anything with columns.
4. Run the loop:

python3 qa/fix_toc.py workspace/wiki/OWNER.REPO.wiki --bak
python3 qa/qa_wiki.py workspace/wiki/OWNER.REPO.wiki \
    --terms workspace/terms.json --ban workspace/ban.json --strict

5. Fix every error; read every warning in context before "fixing" the prose (some warnings are the system working: a negated banned phrase should stay visible).
6. Update PROGRESS.json: page status, word count.

fix_toc.py --bak writes <file>.bak before touching a page, and its replacement is block-scoped (only the list under ## Contents), with a word-count sanity guard — the guard exists because an earlier TOC regenerator ate a page's lead paragraph, badges and an alert block on a page without a --- separator, silently (PITFALLS D8). Delete the .bak files before publishing.

Home, sidebar and footer

Home.md: badges (optional — a third-party badge host is a tracking consideration), a 1–2 paragraph summary, key features as a list, a five-minute quick start where every command was executed, and a navigation table pointing at every section. The scaffold provides all slots.

_Sidebar.md: grouped by meaning (Overview / Install / Usage / Operating / Reference), not alphabetical; must link every page (auditor-enforced); the scaffold derives groups from PROGRESS.json when you pass --progress.

_Footer.md: version, license, repository link, issue link, key page links, and the line that anchors the whole wiki's trust claim — "Facts in this wiki are verified against the source at commit SHA". It renders on every page, so one dead link there is a site-wide error; the scaffold derives its links from the actual page list for exactly that reason.

---

See also

• QA and Audit Guide — the full check list and how to fix each error class
• Tool Reference — new_page.py and fix_toc.py flags and internals
• The Four Phase Workflow — where writing sits in the pipeline
• Publishing and Delivery — what happens to the pages after zero errors
• Glossary — the canonical vocabulary