# Writing a page

The rules a wiki page must meet: frontmatter, headings, relative links, the scripture rule, glossary terms, quizzes and code excerpts, verified stamps, and how a sibling page reaches the site.

- Page: <https://docs.gurbanisoul.com/contributing/writing-docs/>
- Updated: 2026-10-12
- From the Sri Guru Granth Sahib Ji — Knowledge Base wiki. Sri Guru Granth Sahib Ji is quoted verbatim, cited by Ang, and never altered.

---

## 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`](https://github.com/Algorythmos-AI/sggs-platform/blob/integration/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](https://docs.gurbanisoul.com/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

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