cf-docs-rfc-proposal

Notes round — results

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

What each tool did with the four test pages’ notes. A summary across tools comes first, then one section per tool, then how each tool maps the note kinds, what happens to what notes hold, how notes read in the source, and the conventions to record. How the pages were chosen and what the modes mean: README. Per-page notes: intent/. How the book writes notes: survey.

How to read the results:

All checks ran on 2026-10-10 against the published pages saved that day, with the tool versions the earlier rounds pinned, plus Starlight’s Markdoc preset (@astrojs/starlight-markdoc 0.7.0) for its aside tag.

Summary

Every tool keeps every note, in both modes: on all four pages, in passthrough and native, the notes check passes for all 16 notes and the outline check for every heading, in Docusaurus, Zensical, Starlight and Antora (checks). What differs is the cost: which changes the HTML notes need before a tool takes them, and what each tool’s own admonition can say about the kind.

  Docusaurus Zensical Starlight Antora
Notes check, passthrough 16 of 16 16 of 16 16 of 16 16 of 16
Notes check, native 16 of 16 16 of 16 16 of 16 16 of 16
Native syntax :::warning[Important] … ::: !!! important + indented body {% aside type="caution" title="Important" %} … {% /aside %} IMPORTANT: …, or [IMPORTANT] + ==== block
Book’s three kinds as native types none of important, caution documented; mapped, title kept any name accepted; theme styles note only note and caution (no important); all three mapped by severity, title kept all three
HTML notes as written 3 of 4 raw pages fail to compile; the one that compiles has empty notes and a React error build unchanged, except a note never closed, which swallows the rest of the page a note never closed stops the build; elsewhere words run together and > becomes a blockquote, silently in passthrough blocks; a Markdown code span inside stays literal
Changes passthrough needs <p> notes as <div>, blank lines around notes inside <td>/<li>, <br />, notes closed notes closed note text on one line, &#32; and &gt; in three places, notes closed <code> for one Markdown code span
Note in a list indented directive indented admonition indented tag + continuation; open block after a nested list
Note in an HTML table cell directive inside the JSX <td> md_in_html attributes on table, row and cell; stray <tr> removed tag inside the <td> AsciiDoc table with an a\| cell
Note held in a variable partial imported as a component partial included with <% include %> partial tag include::partial$…[]
The kinds look different (default theme) yes: note grey, important amber, caution red no: all blue, titles differ yes: note blue, important amber, caution red label colour differs, box the same
Build checks links in notes native only (HTML links are not checked) native (Markdown links) no no

Docusaurus 3.10.2

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

Summary

Grid

Mode cf-backup using-vol-services healthchecks routes-domains
passthrough same; 3/3 same; 4/4 same; 4/4 same; 5/5
native same; 3/3 same; 4/4 same; 4/4 same; 5/5
raw does not compile does not compile does not compile same; 2/5 (3 empty)

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

Zensical 0.0.69

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

Summary

Grid

Mode cf-backup using-vol-services healthchecks routes-domains
passthrough same; 3/3 same; 4/4 same; 4/4 same; 5/5
native same; 3/3 same; 4/4 same; 4/4 same; 5/5
raw 4 of 7 headings; 1/3 (as passthrough) (as passthrough) (as passthrough)

Starlight 0.42.6

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

Summary

Grid

Mode cf-backup using-vol-services healthchecks routes-domains
passthrough same; 3/3 same; 4/4 same; 4/4 same; 5/5
native same; 3/3 same; 4/4 same; 4/4 same; 5/5
raw stops the build same; 3/4 same; 2/4 same; 4/5

Antora 3.2.1

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

Summary

Grid

Mode cf-backup using-vol-services healthchecks routes-domains
passthrough same; 3/3 same; 4/4 same; 4/4 same; 5/5
native same; 3/3 same; 4/4 same; 4/4 same; 5/5
raw — same; 3/4 (a code span lost) — —

How each tool maps the kinds

Decision (this round), for review: keep the title everywhere. Where the tool accepts the book’s kind names (Zensical, Antora), keep them. Where its set of types is closed and lacks important (Docusaurus, Starlight), map all three kinds onto its types by severity, so that the three kinds stay three different boxes. In Starlight that puts Important on caution and Caution on danger, although Starlight has a caution type. The book itself does not tell the kinds apart by look (all three are the same yellow box), so the look is the template’s choice, not content.

Book’s kind Published look Docusaurus Zensical Starlight Antora
note yellow box, bold “Note” :::note (grey) !!! note (blue) type="note" (blue) NOTE: (blue label)
important the same yellow box, “Important” :::warning[Important] (amber) !!! important (blue, unstyled) type="caution" title="Important" (amber) IMPORTANT: (red label)
caution the same yellow box, “Caution” :::danger[Caution] (red) !!! caution (blue, unstyled) type="danger" title="Caution" (red) CAUTION: (purple label)
warning (2 notes, archive/ only) pink box not tested not tested not tested WARNING: exists

Colours from the browser check. Other maps are possible: Docusaurus’s own legacy alias puts important on info (Types.tsx L30). The map is one table per site, applied by the converter; no page names a tool’s type for a reason of its own.

Review (Docs WG lead, 2026-10-10): open. First find out whether an extension, HTML the build injects, or CSS can give Docusaurus and Starlight the book’s kind names. If none can, keep a tool’s own type where it has the book’s name, such as Starlight’s caution for Caution, and accept that Important and Caution may then look alike: the price of not writing plain HTML. Until that test is done, the map above is what was tested, not the convention.

What notes hold

Notes never closed

Two of the four notes the book leaves open are on cf-backup. The book’s Markdown processor wraps each in a paragraph and the browser ends it at the next block, so the published page is right (published copy, line 603). As written: Zensical loses the rest of the page, Starlight and Docusaurus stop, Antora does not apply (every page is rewritten). Closing them is cleanup, not a change of content (R-24 markup cleanup before conversion).

Notes in a table cell

healthchecks note 3 sits in an HTML table cell after the cell’s text. It stays in the cell in every mode (place table in every check). Native mode needs each tool’s way into a cell: nothing in Docusaurus and Starlight but blank lines, md_in_html attributes and a cleaned table in Zensical, an AsciiDoc table with an a| cell in Antora.

A note held in a variable

using-vol-services opens with <%= vars.external_vol_win_note %>, whose value is a whole HTML note. Passthrough renders the value as markup in every tool (Docusaurus and Starlight through the tables round’s HTML-variable forms). Native mode cannot put an admonition in a variable the way the book does, so the note became a partial in each tool, holding the tool’s admonition, included where the variable was; it passes the notes check in all four. Decision (this round): this is the converter’s rule for the 7 note-valued variables pages use; the 5 unused ones need no conversion (survey). Accepted (Docs WG lead, 2026-10-10).

How notes read in the source

The same note, healthchecks note 4, as each mode writes it:

<p class="note important">
<span class="note__title"><strong>Important</strong></span>
For HTTP apps, <%= vars.company_name %> recommends setting the health check type to <code>http</code> instead of a simple port check.
</p>
:::warning[Important]

For HTTP apps, {vars.company_name} recommends setting the health check type to `http` instead of a simple port check.

:::
!!! important

    For HTTP apps, <%= vars.company_name %> recommends setting the health check type to `http` instead of a simple port check.
{% aside type="caution" title="Important" %}

For HTTP apps, {% $vars.company_name %} recommends setting the health check type to `http` instead of a simple port check.

{% /aside %}
IMPORTANT: For HTTP apps, {company_name} recommends setting the health check type to `http` instead of a simple port check.

Every native form drops the title span and the closing tag; the kind is on the first line. AsciiDoc’s is one line. Docusaurus and Starlight show a type that is not the book’s kind (warning, caution for Important), with the kind as a title beside it. Zensical’s depends on indentation. In every native form the note’s text is Markdown (or AsciiDoc), so code and links read as they do in the rest of the page (R-11 readable source).

Conventions to record

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

  1. Write every note as the tool’s own admonition (native mode). It passes every check in every tool, and needs no workaround inside the note.
  2. Keep the title. The admonition’s title is the source’s title (Note, Important, Caution), written out where the tool’s type has another name.
  3. Map the kind through one table per site: the kind’s own names where the tool accepts them (Zensical, Antora); otherwise all three by severity (Docusaurus: note, warning, danger; Starlight: note, caution, danger). The look of each kind is the template’s. Open (Docs WG lead, 2026-10-10): extensions and CSS are to be tested first (how each tool maps the kinds).
  4. Close every note before converting, where the browser closed it.
  5. A note’s HTML list becomes the format’s list, inside the admonition; a list that holds a note becomes the format’s list too, so the note can be an admonition.
  6. A note held in a variable becomes a partial holding the admonition, included where the variable was. Accepted (Docs WG lead, 2026-10-10).
  7. If HTML notes are kept (passthrough): Docusaurus writes them as <div class="note">; Starlight writes each note’s text on one line and escapes > and the spaces Markdoc drops; Antora writes Markdown inside them as HTML. The template then has to style .note and its kinds, as no theme does.
  8. The notes check runs on every converted page, beside the outline check: checks/notes.py.

Requirements

Not yet written