cf-docs-rfc-proposal

Concept: Notes and admonitions

Status: Done, with open items (listed under Not yet written). The survey, the conversions and the checks are done; the map from kinds to types stays open. Results: results.md.

This round asks whether the book’s notes survive conversion into each hands-on tool: their kind, their title, their words and what they hold, and where they sit on the page (R-07 notes and admonitions). It adds a notes check beside the headings round’s outline check.

Terms used below:

Progress

Test pages

Page Repository Notes Cases
cf-backup cloudfoundry/docs-bbr, whole page 3 a <div> note holding a list; the Caution kind; two notes never closed
using-vol-services cloudfoundry/docs-dev-guide, the opening and the NFS section of its partial 4 a note held in a variable; notes in a list step and inside an HTML list item; a Markdown code span, <br> and >= inside an HTML note
healthchecks cloudfoundry/docs-dev-guide, whole page 4 the Important kind; a note in a table cell; a variable in a note
routes-domains, Domains section cloudfoundry/docs-dev-guide (copied in the headings round) 5 the common shapes: <p> and <div> notes with code and links; two notes in a row

How they were chosen. Decision (this round): from the survey’s rows, few pages that together hold the common shapes and the hard cases: notes holding lists, code, links and variables; notes in lists, table cells and variables; Markdown inside HTML; notes never closed. routes-domains was the only page from the earlier rounds with notes, and was reused. Two patterns are on no test page: a code block inside a note (2 notes in the book) and the warning kind (2 notes, archived); see Not yet written.

Notes check

checks/notes.py reads a built HTML page and lists its notes, or compares them with a notes file. It needs only Python 3.

# The notes on a page
python3 -I checks/notes.py published/healthchecks.html

# A notes file from a page (the intent files were made this way)
python3 -I checks/notes.py published/healthchecks.html --emit

# A built page against the notes file, with the site's map from kind to type
python3 -I checks/notes.py BUILT.html --expect intent/healthchecks.notes --map note=note,important=warning,caution=danger

# Both checks on every page and mode of one site (run from sites/<tool>, after make build)
../../checks/check-site.sh build note=note,important=warning,caution=danger

What it does:

It is written to be shared: it knows nothing about these pages. make check in each site runs it and the outline check on every page in passthrough and native (checks/check-site.sh); make check-raw runs them on the raw mode. A browser check, checks/notes-browser.mjs, records console errors and each note’s label and colours; appearance is not compared, but it shows whether the kinds look different and whether a note has a box at all.

The outline check (../headings/checks/outline.py) gained one option, --until ID, which ends a --section before the heading that carries ID, for using-vol-services, an excerpt that stops inside a section. Without it the check behaves as before.

Method

  1. Survey the notes of every docs-* repository.
  2. Choose pages that hold the patterns, preferring pages already converted.
  3. Write the intent: each note’s kind, title, contents and place, and the notes file the check compares against.
  4. Convert by hand into each tool. Passthrough first, then native, which differs from passthrough only in the notes (compare any two modes’ files to see). Raw keeps the notes exactly as written, where that differs.
  5. Build and check with the notes check, the outline check and a browser.
  6. Record conventions per tool (sites/<tool>/CONVENTIONS.md).

Each tool keeps the version and configuration of the earlier rounds. Starlight adds its own Markdoc preset (@astrojs/starlight-markdoc 0.7.0) for the aside tag, and takes only that tag from it.

Layout

concepts/notes/
├── README.md          this file
├── results.md         results per tool, kinds, conventions
├── survey/            note survey: survey.py, summary.py, notes.csv, shas.txt, README
├── source/            new test pages, verbatim, plus SOURCES.md
├── published/         the three new published pages, as served on 2026-10-10
├── intent/            per page: <page>.md (notes, cases, cleanup) and <page>.notes (what the check compares)
├── checks/            notes.py, check-site.sh, notes-browser.mjs
├── sites/             docusaurus/, zensical/, starlight/, antora/: pages per mode, config, Makefile, CONVENTIONS.md
└── results/           check output per tool and mode, build warnings, browser checks, built HTML excerpts

Each site builds with make build and checks with make check and make check-raw. Build output and installed packages are ignored by git; the results in results/ were produced from copies of the sites built outside the repository.

Decision (2026-10-10): the saved published pages stay in the repository so the checks can be rerun after the live site changes. They, and the rest of this round’s working files, can be removed once the conversion is complete.