Writing a page

Frontmatter and headings

Every page begins with title (8–120 characters) and description (40–200) and a body whose first # H1 equals the title (GitHub shows it; the site strips it). Pages under docs/process/, docs/engineering/ and docs/architecture/ must carry verified: {commit, date} — the commit you last read the page against — and the gate warns when code the page cites (a code excerpt, a linked source file, a poster’s Source of truth) changes after that commit; the weekly docs-freshness issue lists the same pages.

The description is read by people. It is shown under the page’s title as a summary, as well as to search engines and in link previews. Write one or two sentences saying what the page covers, and do not open it with the page’s first sentence: a description that repeats the opening paragraph is left out of the page.

Where a page appears in the sidebar

A new page in an existing directory appears in that directory’s sidebar group by itself, after the directory’s README.md (listed as “Overview”), ordered by sidebar.order and then by title. The sidebar shows the title unless the page sets a shorter sidebar.label; keep labels to 48 characters. A page at the top of docs/, or a new directory, must be placed in docs-site/sidebar.mjs — the build fails until it is, because every published page must be reachable from the sidebar. draft: true or sidebar.hidden: true leaves a page out. The sidebar is read when the site starts, so restart make docs-dev after adding or removing a page.

Links

Write relative Markdown links as you would for GitHub (../data/line-record.md#explore-real-records). The site turns them into page links, sends links to code files to GitHub at the right ref, and turns a GitHub link to a document the wiki pins into the wiki page. Never a root-absolute /… link, never localhost. Anchors are checked with GitHub’s slug rules.

The scripture rule

No verse is ever typed into a page. Scripture appears in exactly two ways: fetched live by a widget, verbatim with its Ang; or as a cited blockquote whose last line is — Sri Guru Granth Sahib Ji · Ang N, which the gate verifies against the pinned database line by line. A run of Gurmukhi of four words or thirty characters outside a code span is refused; names and tokens (ਰਹਾਉ, ਮਃ, a raag’s name) go in code spans or stay short. Posters and diagrams carry no scripture at all.

Terms, quizzes and excerpts

• [[Term]] or [[Term|as shown]] makes a hover-card from the glossary; an unknown term fails the build. Add the term first.
• <!-- sggs:quiz --> followed by a ```quiz fence: Q: lines, - answers, one marked ✓, optionally — why. It reads as text on GitHub.
• <!-- sggs:code file="…" symbol="…" repo="…" --> shows a function read from the source at build time; never paste code that could drift.
• <!-- sggs:steps --> on the line before an ordered list sets it as a procedure: numbered circles joined by a line. Use it for three to nine actions done in order (a runbook, a set-up). Do not use it for concepts, and never for the structure of scripture. Everywhere else — GitHub, paper, the Markdown export — the list is a plain numbered list.

Gurmukhi is marked as Punjabi for you. The build wraps every run of Gurmukhi in prose, tables and inline code in lang="pa" (docs-site/plugins/rehype-lang-pa.mjs), so a screen reader reads it as Punjabi. Write the text as it is; do not add <span lang> by hand.

Notes and quotations look different on purpose. A blockquote that opens with bold text and has no Gurmukhi becomes a callout: a tinted box with a thick rule. A blockquote that quotes scripture stays a quotation: no tint, no box, a thin rule, the Gurmukhi and its Ang. Never dress a note as a quotation, or a quotation as a note.

The full widget list is in docs-site/plugins/widgets.schema.json; every widget needs a fallback sentence within three lines.

Numbers

A number that describes the data or the code should come from it: generate the table, read the constant, quote the test. Where that is not possible, name the file and the commit. The gates check what they can (search modes, verify thresholds, generated pages); the rest is your verified stamp.

Sibling repositories

The data and app repositories’ documents are published here by pin (docs-site/sources.lock.json); to change one, edit it in its own repository, and bump the pin with python3 tools/fetch_sibling_docs.py --update <name> in a small pull request here.

Before the pull request

make docs-check    # every gate the docs job runs, in seconds
make docs          # the full build, with every Mermaid rendered and every link resolved