Status: Done, with open items (listed under Not yet written). The conversions and checks are done; the id convention is accepted. Results: results.md.
This round asks whether a page’s heading tree and its heading anchors survive conversion into each hands-on tool, and it adds the automated check the concept list calls for: an outline check that compares the headings of a converted page with the published page (R-01 content and outline survive).
Terms used below:
h1 to
h6), its text, and the ids it carries.page.html#about).
Today’s sources write one as an empty HTML anchor at the start of a
heading: ## <a id="about"></a> About metadata.<a id> and HTML <h4>
tags included; native: each id written with the tool’s own heading
syntax, HTML headings written as the tool’s headings; native-plain:
native with no ids written, so the tool makes them all. Native-plain
shows what a conversion that drops the ids would break..anchors file the check reads), and the links from
other pages and repositories that point at them: intent/.| Page | Repository | Headings | Cases |
|---|---|---|---|
metadata |
cloudfoundry/docs-cf-admin (copied in the tables round) | 32, ##–#### |
deep tree; an explicit id on every heading; five heading texts used twice; title from front matter |
troubleshooting_slow_requests |
cloudfoundry/docs-cf-admin (copied in the tables round) | 12, ##–### |
a variable in a heading; ids that links on the page point to |
access-control |
cloudfoundry/docs-services | 8, ##–#### |
skipped levels (## then ####, then ###); headings with no explicit id |
routes-domains, Domains section |
cloudfoundry/docs-dev-guide | 17 of the page’s 42, ##–##### |
HTML <h4> tags next to Markdown ####; the deepest level in the set; ids linked from other repositories |
Every page takes its title from its front matter, not from a # heading.
How they were chosen. Decision (this round): the two tables-round pages
that qualified were reused, because their bodies were already converted
in every tool; only their heading lines change between modes. The other
cases came from a scan of the headings in the book’s repositories at the
table survey’s commits (survey/shas.txt). The
first scan was not kept; it is redone, over all 12 of the book’s
repositories, in the heading survey. It finds two pages
with skipped levels after the first heading (access-control and docs-bbr
restore; the first scan found only access-control) and two with HTML
heading tags (routes-domains has 15; services/application-binding has
one). No heading holds code; one page holds links in headings (see
Not yet written).
checks/outline.py reads a built HTML page and prints its outline, or compares two pages. It needs only Python 3.
# The outline of one page
python3 -I checks/outline.py published/metadata.html
# A built page against the published one, with the anchors it must keep
python3 -I checks/outline.py published/metadata.html BUILT.html --anchors intent/metadata.anchors
# A page built from an excerpt: only the title and one section
python3 -I checks/outline.py published/routes-domains.html BUILT.html --anchors intent/routes-domains.anchors --section domains
# Every page in every mode of one site (run from sites/<tool>, after make build)
../../checks/outline-site.sh build # Docusaurus; site for Zensical and Antora, dist for Starlight
What it does:
main#js-content, or
each tool’s article), skipping navigation and tables of contents.It is written to be shared by later concepts: it knows nothing about these
four pages. make check in each site runs it on every page and mode. It
does not compare body text; the tables round’s
text-diff.py does that.
<tool>/CONVENTIONS.md).Each tool keeps the tables round’s version and configuration, without the table extensions and table stylesheets no page here uses. Antora adds two attributes for generated ids (conventions).
concepts/headings/
├── README.md this file
├── results.md results per tool, ids, conventions
├── broken-links.md links to the test pages that are already broken today
├── source/ new test pages, verbatim, plus SOURCES.md
├── published/ the four published pages, as served on 2026-10-10
├── survey/ the heading survey: scan.py, headings.csv, pages.csv
├── intent/ per page: <page>.md (tree, anchors, inbound links) and <page>.anchors
├── checks/ outline.py (the shared outline check), outline-site.sh
├── sites/ docusaurus/, zensical/, starlight/, antora/: pages per mode, config, Makefile, CONVENTIONS.md
└── results/ check output, outlines, tables of contents, build warnings, browser checks
Each site builds with make build and checks with make check. 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.