Keeping the docs current

From the repository

This page is docs/CONTRIBUTING-docs.md, included when the site is built. Edit it there.

niso’s docs site is docs/site/ (Astro Starlight). Most of it is generated or included from the repository when the site is built, so it can’t fall behind the code. The rest is written by hand, and every merged feature updates it (DECISIONS, Process). This page says which page to update for which change and how the docs check keeps hand-written pages honest.

Build, serve, check

cd docs/site && pnpm install --frozen-lockfile   # once; everything after runs offline
docs/site/build.sh                               # build into docs/site/dist
docs/site/build.sh dev --host 0.0.0.0 --port 4321   # serve with live reload
docs/site/check.sh                               # the docs check
docs/site/check.sh --slow                        # also the slow runnable blocks (device builds)

tests/check.sh runs docs/site/check.sh, and fails with the install command when the site’s packages aren’t installed (NISO_SKIP_DOCS=1 skips the docs check instead); tests/check.sh --docs-slow passes --slow. The generator also runs cargo xtask docs, which writes the composed niso.h and niso_runtime.h and their sections to target/docs/ (or a directory you name).

What is generated and what is written

Generated on every build, never committed (docs/site/.gitignore lists the paths), from these sources:

Pages	Source	Generator
Reference, Web APIs	idl/*.webidl, niso.h, docs/site/data/platform-notes.yaml, tests/wpt/baseline.json, web-features	scripts/web-apis.mjs
Reference, C API	niso_runtime.h’s sections (crates/niso-compose/sections.txt), niso.h, niso_app.h, niso_engine.h, niso_js.h, niso_intl.h	scripts/c-api.mjs
Reference, Render stream format	the comments in crates/niso-core/include/rendering.h	scripts/c-api.mjs
Reference, Crates	cargo metadata, cargo xtask layers, xtask/layers-allowlist.txt, each CONTRACT.md, README’s layout	scripts/includes.mjs
Reference, Command line	the usage comment at the top of each tool’s source	scripts/cli.mjs
Compatibility, Real apps	docs/compat/*.md and their images	scripts/includes.mjs
Compatibility, Web platform support; Baseline banners	tests/wpt/baseline.json, tests/wpt/excluded-features.txt, web-features	scripts/support.mjs
Contributing, The repository	README.md	scripts/includes.mjs
Architecture (all but the overview)	docs/architecture/*.md, DECISIONS.md	scripts/includes.mjs
Design notes	every other docs/**/*.md, repros/*/README.md	scripts/includes.mjs
Contributing, Freshness	every page’s stamp and git history	scripts/freshness.mjs

So for those, edit the source, not the site. A new Markdown file under docs/ appears under Design notes by itself; a new crate appears in the crate table; a new CONTRACT.md gets its page; a new header section gets its page.

Everything else under docs/site/src/content/docs/ is written by hand.

Which page to update

You changed	Update
A build script’s flags, or what a getting-started command prints	start/getting-started.mdx, start/apple.mdx, start/android.md. The default check fails on a flag a page passes to a repo script or tool that its source no longer has; what a device build prints is only checked by its slow blocks, with --slow
What a page can do (a new web API, element, CSS property, meta tag or attribute niso reads)	The concept page for the area (concepts/), the matching reference/other/ page, and a guide if it’s something apps build with
A native control, or how one maps per platform	concepts/native-controls.mdx, reference/other/elements-and-controls.md, and platform-notes.yaml for member-level notes
The platform sheet or tokens (crates/niso-core/ua/)	concepts/platform-style.mdx, reference/other/css.mdx
Surfaces, widgets, Live Activities, CarPlay	concepts/surfaces.mdx, guides/home-screen-widget.mdx, guides/live-activity.mdx, platforms/apple.md
A host (hosts/*)	platforms/<platform>.md, concepts/hosts.md
An engine or binding	concepts/engines.md, languages/*
The render stream	The comment in rendering.h (the format page is generated from it), and concepts/rendering.md if the model changed
The C API	The header section’s comments (generated pages), and the language pages if usage changed
Storage, workers, security, text	concepts/storage.mdx, concepts/workers.mdx, concepts/security.mdx, concepts/text.md, and the design note under docs/
An app of the corpus	docs/compat/apps.md (included), and guides/app-corpus.md if how to run it changed
WPT or the Baseline score	Record with cargo run --release -p niso-wpt -- --update; the support table and banners follow. guides/wpt.md if the workflow changed
Something planned became real, or the reverse	start/status.mdx and the page that marks it planned
Anything a hand-written page covers	That page: the docs check lists it as possibly stale until you do (below)

Not sure? Run docs/site/check.sh: it lists the pages whose covered files your branch touched. The check also fails when a page this table names doesn’t exist.

Stamps: “Checked against ”

Every hand-written page says which commit it was last checked against, who checked it, and which repo files it describes:

---
title: Getting started
verified: 001571662dd440100578fdc0fe2e48e3470983a1   # a full commit sha
checked_by: "teo"
covers: [hosts/apple/build.sh, crates/niso-quickjs/src/bin/niso-run.rs, examples/build.mjs]
---

The page shows “Checked against on by ” under its title. That is all a stamp guarantees: someone re-read the page against that commit. If no later commit changed the covered files, it adds “The files it covers are unchanged since”; otherwise “N later commits changed the files it covers; it may be out of date” with a link to the range. The Freshness page lists every stamp.

After re-reading a page against the code (and fixing it), move its stamp to the current commit. --by is required, so a stamp can’t be bumped without someone naming themselves as the reader, and the script first lists the commits since the old stamp that changed what the page covers, which is what the reread has to check:

docs/site/scripts/verify-page start/getting-started.mdx --by teo
docs/site/scripts/verify-page concepts/rendering.md --by teo --covers crates/niso-core/src/render.rs crates/niso-core/include/rendering.h

Drift is reported, never a failure: the docs check prints it, and on a branch it also lists covered files the branch changed without touching the page. If the page is still right, either bump its stamp or say so in a commit message with a trailer, and the check stops listing it for that branch:

Docs-Reviewed: start/getting-started.mdx

The check does fail when a hand-written page has no stamp, the commit isn’t in history, or a covers glob matches nothing.

Code that runs

Commands a reader should run are runnable blocks, and the check runs them:

• ```sh run runs the block with bash (set -e, pipefail) from the repo root.
• ```js run runs the block as a script with niso-run (built once per check).
• ```c compile compiles the block with cc -fsyntax-only against the composed headers.
• ```svelte title="examples/hello/App.svelte" write writes a file the page’s later blocks use; the check deletes it afterwards and refuses to overwrite a tracked file.

Options follow run: slow (only with --slow: device builds, anything over half a minute), os=macos or os=linux, timeout=SECONDS, cwd=scratch (a temp directory under target/docs-check/ instead of the repo root), and for js, args="--dump". A block right after it marked ```txt output is its expected output, compared after trimming trailing spaces; a line ... matches any number of lines. A command that must not run (one that launches a simulator, say) is a plain ```sh block; keep those rare and say why.

References that resolve

• Cite code with components in MDX pages. <Code path="crates/niso-core/src/render.rs" symbol="pub fn" /> links to the line where the symbol is; <Excerpt path="examples/lang/c/timer.c" start="niso_app_main" end="^}" /> shows those lines from the file itself. The build fails if the file or the text is gone.
• In prose, the check scans inline code: a repo path (crates/..., hosts/..., docs/..., DECISIONS.md), a niso_crate::item path and a niso_* C name must exist (C names in the composed headers). So do GitHub links to main. Write paths without placeholders where you can; a path with <, * or ... in it isn’t checked.
• Internal links are checked by the build (starlight-links-validator), anchors included.

Numbers come from data

Don’t type a measured number (a pass rate, a size, a timing, a count of tests) into prose; the check fails on numbers with %, KB/MB/KiB/MiB or ms. Show it from the file the harness writes:

<Metric source="tests/wpt/baseline.json" path="summary.high.subtestPassRate" format="percent" />

It renders the value with the commit and date the file was recorded at. Each source is registered in docs/site/data/metrics.yaml with the command that records it, the code it measures (measures) and max_commits: the check fails when more commits than that have touched the measured code since the file was recorded, and asks for a new recording. A number in a page’s prose that isn’t a measurement (a version, a platform’s limit) is fine; put it in inline code if the scan trips on it.

Screenshots

An image a page shows (hand-written or included) must have its provenance in docs/site/data/screenshots.yaml: the harness command, the commit it was recorded at, and the code it depicts. The check fails on an image without an entry and on one more than max_commits behind what it depicts, as for numbers. Copy a new capture in with

docs/site/scripts/record-screenshot target/apps/todomvc-vue/quickjs.png docs/compat/apps/todomvc-vue-quickjs.png \
  --by "tests/apps/run.sh todomvc-vue --screenshot" --measures 'crates/niso-core/**' 'hosts/iced/**'

Baseline banners

A page about a web feature starts with a banner:

import Baseline from '../../../components/Baseline.astro';

<Baseline feature="fetch" />

It shows the feature’s Baseline status on the web (from the web-features release tests/wpt/fetch.sh pins) and niso’s: full, partial with its pass rate, not yet, not run (and why), or excluded (and why), per system, from tests/wpt/baseline.json at the commit that recorded it. Generated Web API pages have one already. An id web-features doesn’t know fails the build.

Writing

Plain, accurate, concrete prose: what a thing does and how. No marketing. Where something is planned, in progress or on a branch, say so on the page, and say when it lands. Link to MDN for what a web API does and spend niso’s words on what differs. App developers and contributors both read the site: app pages say what you can build and how; contributor pages (Contributing, Architecture, the C API, crates, design notes) say how niso is built.