Write a docs page

Every hand-authored page in these docs is a MyST notebook — jupytext frontmatter plus a kernelspec — so any of them can run live code-cells with real output and plots. There are three genres, split by reader and by where their cells execute:

• Tutorials (the five hands-on chapters — docs/basics/, pipeline/, fitting/, visualization/, vendor/) demonstrate a task step by step, and are the test suite: uv run test runs their asserts.

• Explainers (docs/concepts/) are motivated narrative for why something is the way it is — executed too, so their live claims are asserted like any tutorial cell.

• Guides (docs/contribute/) are procedural pages like this one; executed on the PR build, and — once they carry a kernelspec — by uv run test as well.

The four house-style rules — motivated narrative, one home per concept, every article stands alone, and the MyST palette carries the argument — are the single source of truth in CLAUDE.md § Documentation style.

Working with Claude Code¶

The docs-page skill owns the cell structure, the hidden-assert convention, and the TOC step, and it ships a stdlib-only checker (check_docs.py) that catches what the build stays silent about — a missing target, a dead .ipynb link, a drifted kernel name. Run it on the page you are editing:

uv run python .claude/skills/docs-page/check_docs.py docs/<path>/<page>.md

Its errors gate CI — the Docs style job in ci-fast.yml runs the same command over the whole tree on every PR, so a page with errors is a red build. Its warnings deliberately do not: they are real drift, but too judgment-dependent to block a merge on. The checklist:

- [ ] Genre identified; the matching template and `patterns.md` read
- [ ] Frontmatter exact, `display_name: Python 3 (xmris)`
- [ ] `(target)=` + single H1 is the very first content; a target above every header
- [ ] Reader-facing cells use plain dim strings; config singletons only in hidden cells
- [ ] Synthetic MRS data comes from `simulate_fid`; tutorials open with the functions-used table
- [ ] TOC entry in `docs/myst.yml` (unless `testonly_`); no `.ipynb` links
- [ ] New `doi.org` link frozen into `docs/myst.doi.bib` (`myst build --doi-bib`) and committed
- [ ] `check_docs.py` passes on the page (0 errors)
- [ ] Tutorial only: single-notebook nbmake run is green
- [ ] Only the `.md` staged