cf-docs-rfc-proposal

Headings round — results

Status: draft, incomplete — covers what is known as of 2026-10-10.

What each tool did with the four test pages’ headings. A summary across tools comes first, then one section per tool, then how ids are made, what happens to skipped levels and repeated headings, and the conventions to record. How the pages were chosen and what the modes mean: README. Per-page heading trees and anchors: intent/.

How to read the results:

All checks ran on 2026-10-10 against the published pages saved that day (published/), with the tool versions the tables round pinned.

Summary

Every tool keeps every heading tree: all 48 pages (4 pages, 3 modes, 4 tools) pass the outline check, with the same levels and text as the published page, skipped levels and repeated headings included. Every tool keeps every explicit id in passthrough and in native. The tools differ in what happens around the headings: the table of contents, the ids they make themselves, and what the build reports.

  Docusaurus Zensical Starlight Antora
Outline check, all modes same, 12 of 12 same, 12 of 12 same, 12 of 12 same, 12 of 12
Anchors, passthrough and native 69 of 69 69 of 69 69 of 69 69 of 69 with the id settings below; 65 of 69 with the defaults
Anchors, native-plain 11 of 69 11 of 69 11 of 69 11 of 69 (0 with the defaults)
Native id syntax ## Text {#id} ## Text {#id} ## Text {% #id %} [[id]] above == Text
Headings as written (<a id> inside) builds; React hydration error in the browser; table of contents nests a link in a link builds cleanly; anchors work builds cleanly; anchors work builds with +++…+++ around the anchor; anchors work
HTML <h4> headings as written render; not in the table of contents render; not in the table of contents render; not in the table of contents render in a passthrough block; not sections, not in the table of contents
Generated ids about-metadata; repeats -1, -2 about-metadata; repeats _1, _2 about-metadata; repeats -1, -2 _about_metadata, repeats _2; with idprefix: '', idseparator: '-': about-metadata, -2
Variable in a heading heading shows the value; table of contents shows vars.app_runtime_abbr; generated id uses the expression value everywhere value everywhere value everywhere
Skipped levels kept, no message kept, no message kept, no message kept, with a warning for each
Table of contents h2–h3 h2 and below h2–h3, plus “Overview” h2–h3, built in the browser
Build checks anchors yes, but misses <a id> anchors yes, all kinds no no warning for the excerpt’s <<routes,Routes>>, whose target is missing

Docusaurus 3.10.2

Site: sites/docusaurus/ — conventions: CONVENTIONS.md.

Summary

Grid

Mode metadata troubleshooting access-control routes-domains
passthrough same; 32/32 same; 12/12 same; 8/8 same; 17/17
native same; 32/32 same; 12/12 same; 8/8 same; 17/17
native-plain same; 3/32 same; 0/12 same; 5/8 same; 3/17

“same” is the outline check; the fraction is anchors kept.

Other findings

Zensical 0.0.69

Site: sites/zensical/ — conventions: CONVENTIONS.md.

Summary

Grid

Mode metadata troubleshooting access-control routes-domains
passthrough same; 32/32 same; 12/12 same; 8/8 same; 17/17
native same; 32/32 same; 12/12 same; 8/8 same; 17/17
native-plain same; 3/32 same; 0/12 same; 5/8 same; 3/17

Other findings

Starlight 0.42.6

Site: sites/starlight/ — conventions: CONVENTIONS.md.

Summary

Grid

Mode metadata troubleshooting access-control routes-domains
passthrough same; 32/32 same; 12/12 same; 8/8 same; 17/17
native same; 32/32 same; 12/12 same; 8/8 same; 17/17
native-plain same; 3/32 same; 0/12 same; 5/8 same; 3/17

Other findings

Antora 3.2.1

Site: sites/antora/ — conventions: CONVENTIONS.md.

Summary

Grid (with idprefix: '', idseparator: '-')

Mode metadata troubleshooting access-control routes-domains
passthrough same; 32/32 same; 12/12 same; 8/8 same; 17/17
native same; 32/32 same; 12/12 same; 8/8 same; 17/17
native-plain same; 3/32 same; 0/12 same; 5/8 same; 3/17

Other findings

Anchors and ids

How each tool makes an id

For a heading with no explicit id. From the outlines in results/.

Heading Published Docusaurus Zensical Starlight Antora (settings above)
### Limitations limitations limitations limitations limitations limitations (default _limitations)
## <a id="about"></a> About metadata (passthrough) -about-metadata -about-metadata about-metadata -about-metadata about-metadata
## Example: Label resources with a git commit (native-plain) -example:-label-resources-with-a-git-commit (passthrough form) example-label-resources-with-a-git-commit same same same
second “Add metadata to a resource” (native-plain) -add-metadata-to-a-resource, the same id again …-1 …_1 …-1 …-2
“Use app logs to locate delays in variable” (native-plain) -use-app-logs-to-locate-delays-in-cloud-foundry (passthrough form) …-in-varsapp_runtime_abbr …-in-cloud-foundry …-in-cloud-foundry …-in-cloud-foundry

On the published page every Markdown heading carries two ids, the one made from its text and the <a id> inside it; an HTML heading carries only the <a id>. The published ids are made from the heading’s text including the space after the <a id>, and keep : and . (the Markdown processor’s own rule; this round did not trace which setting of the book turns it on).

Found in the clones of the docs repositories and by GitHub code search on 2026-10-10 (code search covers default branches only, so counts are lower bounds). Full lists with pinned links are in each intent file.

Page Anchors linked from elsewhere Kept: passthrough, native Kept: native-plain
metadata #types (docs-dev-guide), #query (cloud_controller_ng v3 API docs), #reqs, #requirements-reference all, every tool none
troubleshooting_slow_requests none outside the page; five links on the page all none
access-control #enable-access (docs-services, at least 16 other files), #disable-access all none
routes-domains (Domains section) #domains, #private-domains, #shared-domains, #domains-dns all the first three (their text gives the same id); #domains-dns breaks

Already broken today, before any conversion: 81 links in 35 files and 8 repositories, to 7 ids that are not on the pages. They are metadata#-view-metadata-for-an-object (72 links in 28 files, in the Terraform provider’s and a Crossplane provider’s docs, all from four hand-written source lines), access-control#make-plans-public (two repositories), and seven links to five routes-domains ids. Two of the routes-domains links are on the page itself, written in its source: #create-route-w-port (the id is create-route-with-port) and #http-vs-tcp-shared-domains (the id became http-vs-tcp-domains in 2023). Some point at ids generated from older heading text, which disappeared when the heading changed or became an HTML <h4>; others at explicit ids that were renamed. A migration cannot repair these by keeping ids, but fixing the link, a redirect or an added anchor could (R-16 old URLs keep working). The full list, with each source line pinned, the cause and the id each link was most likely meant for: broken-links.md.

Skipped levels and repeated headings

Conventions to record

For cf-docs-migrate convert. Decisions of this round, for review:

  1. Write every id the source writes, in the tool’s own heading syntax (native mode): {#id} (Docusaurus, Zensical), {% #id %} (Starlight), [[id]] (Antora). Do not keep the <a id> inside the heading.
  2. Write HTML headings as the tool’s headings. <h4><a id="x"></a>Text</h4> becomes #### Text {#x} (or the tool’s form): it then joins the table of contents and, in Antora, the section structure.
  3. Keep the published generated id of a heading that has no <a id>, by matching the tool’s id rule to it (Antora: idprefix: '', idseparator: '-') or by writing the id explicitly. Do not keep the published second ids of headings that have an <a id>. Accepted (Docs WG lead, 2026-10-10), with the links already broken today listed for fixing (Links from other pages).
  4. Keep skipped levels. Renumbering is the owner’s decision, recorded as a deviation, not a converter rule.
  5. Give a heading that holds a variable an explicit id (needed in Docusaurus, harmless elsewhere).
  6. The page title stays in the front matter (Docusaurus, Zensical, Starlight) or the document title (Antora); no tool needed an # H1.
  7. The outline check runs on every converted page: checks/outline.py, with the page’s anchors file.

Requirements

Not yet written