cf-docs-rfc-proposal

Variables round — results

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

What each tool did with the five test pages’ variables. A summary across tools comes first, then one section per tool, then each place a variable can sit, what to do with names that are not defined, where values that hold markup should live, and the conventions to record. How the pages were chosen and what the modes mean: README. Per-page uses: intent/. How the book uses variables: survey.

How to read the results:

All checks ran on 2026-10-11 against the published pages saved that day, with the tool versions the earlier rounds pinned.

Summary

In native mode every value is in place in every tool, on all five pages: 85 of 85, with every outline, anchor and note kept (checks). Passthrough shows what a mechanical translation of the tag gets: everything in Zensical; in the other three tools every text value but not Markdown values; in Docusaurus and Starlight not link targets or titles either, and in Docusaurus the table of contents only through the site’s heading plugin.

  Docusaurus Zensical Starlight Antora
Values in place, passthrough 75 of 85 85 of 85 73 of 85 78 of 85
Values in place, native 85 of 85 85 of 85 85 of 85 85 of 85
A variable in the source {vars.name} <%= vars.name %>, as the book {% $vars.name %} {name}
HTML value escaped text, unless the module holds JSX (native) or dangerouslySetInnerHTML markup escaped text, unless the config holds a Markdoc tree (native) or a rawhtml tag markup
Markdown value text, unless the module holds JSX Markdown text, unless the config holds a Markdoc tree text, unless written as HTML
In a code block <CodeBlock> with a template string as written in a fence, as written subs=attributes+ on the block
As a link target <a href={vars.name}>; in a Markdown link, a broken link as written a link tag; in a Markdown link, no link and no message link:{name}[…]
In a heading’s table-of-contents entry the value, through the site’s heading plugin; without it, the expression’s source the value the value the value
In the page title the value written in the front matter the variable in the front matter the value written in the front matter = {name} …
A name not defined, as the book does nothing, silent nothing, silent nothing, silent nothing, silent
A name not defined, reported build error, from a 10-line variables module build error, on_undefined = "strict" (no page named) a check before the build; the build drops the error build fails, attribute-missing: warn and failure_level: warn
An empty value (YAML null) nothing prints None unless written as "" nothing nothing

Docusaurus 3.10.2

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

Summary

Grid

Mode app-ssh-overview routes-domains troubleshooting-router container-security all_metrics
passthrough same; 6/9 same; 50/50 same; 7/8 same; 12/16 title differs; 0/2
native same; 9/9 same; 50/50 same; 8/8 same; 16/16 same; 2/2
raw does not compile — — — —

“same” is the outline check; the fraction is values in place.

Zensical 0.0.69

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

Summary

Grid

Mode app-ssh-overview routes-domains troubleshooting-router container-security all_metrics
passthrough same; 9/9 same; 50/50 same; 8/8 same; 16/16 same; 2/2
native same; 9/9 same; 50/50 same; 8/8 same; 16/16 same; 2/2
raw — — — — the ERB code line stops the build

Starlight 0.42.6

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

Summary

Grid

Mode app-ssh-overview routes-domains troubleshooting-router container-security all_metrics
passthrough same; 6/9 same; 50/50 same; 5/8 same; 12/16 title differs; 0/2
native same; 9/9 same; 50/50 same; 8/8 same; 16/16 same; 2/2
raw heading differs; 1/9 — — — —

Antora 3.2.1

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

Summary

Grid

Mode app-ssh-overview routes-domains troubleshooting-router container-security all_metrics
passthrough same; 6/9 same; 50/50 same; 8/8 same; 12/16 same; 2/2
native same; 9/9 same; 50/50 same; 8/8 same; 16/16 same; 2/2

Every page is AsciiDoc in every mode, so there is no raw mode.

Each place a variable can sit

How the book’s places map to each tool, in native mode. Counts are the book’s uses (survey).

Place (uses) Docusaurus Zensical Starlight Antora
Text, link text, table cell, note (1,238) {vars.name} <%= vars.name %> {% $vars.name %} {name}
Inline code (98) <code>{vars.name}</code> in backticks, as written <code>{% $vars.name %}</code> in backticks
Fenced code (92), <pre> (44) <CodeBlock language="console">{\… ${vars.name}`}</CodeBlock>` as written in a fence [source,console,subs=attributes+]
Heading (27) the reference; the site’s heading plugin writes the value the reference the reference the reference
Link target (3) <a href={vars.name}>…</a> as written {% link href=$vars.name %}…{% /link %} link:{name}[…]; in HTML, subs=attributes+
Page title (1, by ERB code) the value, in front matter the reference, in front matter the value, in front matter = {name} …
Page description (none in the book; tools write one) the value, in front matter, where the first paragraph holds a variable not written not written not written
Expression with a condition (2) — — — —

The two conditions (stacks L11, windows-stacks L9) were not converted. Every tool can write the result; only Zensical and Docusaurus could keep the condition.

Names that are not defined, and empty values

The book has 38 uses of 28 names no key defines and 44 uses of 31 keys with no value; all 82 render as nothing on the published pages (survey). R-04 variables everywhere asks that “a variable that is not defined is reported when the site builds, instead of showing as empty text”; the tables round’s sources note asked for the opposite, empty text, before the requirement was written.

  Docusaurus Zensical Starlight Antora
Default nothing, no message nothing (silent, the earlier rounds’ setting), no message nothing, no message {name} on the page (skip); nothing with drop (the earlier rounds’)
Reported build error: “Variable not defined: vars.no_such_name” and the page’s path build error: “UndefinedError: ‘dict object’ has no attribute ‘no_such_name’”, no page named check before the build: “probe.mdoc:5: Undefined variable: ‘vars.no_such_name’” warning “skipping reference to missing attribute: no_such_name”, file named, no line; fails the build with failure_level: warn
How a Proxy in the variables module (site code) on_undefined = "strict", on_error_fail = true a script with Markdoc’s validator (site code) playbook settings
Empty value nothing “None”, unless written "" nothing nothing

Evidence: Docusaurus, Zensical, Starlight, Antora.

Decision (this round): native mode removes the 4 references the test pages make to undefined names, since they render as nothing today, and requires every name. A reference that is left fails the build in every tool.

Where values that hold markup should live

131 of the book’s 273 values hold HTML or Markdown; pages use 78 of them, 97 times (survey). Most are a sentence with a link, used at the end of a paragraph, list item or table cell; 28 of the 49 uses of an HTML value sit inside a sentence.

Product names

1,060 of the book’s 1,503 uses (71%) read a product name, “Cloud Foundry”, “CF” or “cf”, through app_runtime_abbr and eleven other keys; they cover all 27 headings with a variable and all 33 link texts (survey). Such variables let other books build the same pages with their own names; a comment in overview mentions “private/commercial books”. If no other book builds from these repositories any more, writing the name as text would remove most uses, every heading case, and with it the Docusaurus table-of-contents workaround. Decision (Docs WG lead, 2026-10-11): the names are written as text. No open-source book other than this one builds from these repositories; pivotal-cf/docs-book-tiledev, whose config.yml names docs-services, is a commercial book (convention 9).

The footer’s <%= Time.now.year %> (_book-footer.erb L3) is the book’s one build-time value. It is counted in the survey and not converted: it belongs to the copyright concept and to R-25 build-time values are expected differences. The layouts’ other variables (book_title_short, domain_name, ga_account_id, support_url, and Bookbinder’s header’s) are site settings for each tool’s configuration, not page variables.

Conventions to record

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

  1. One reference form per tool, from one shared file: {vars.name} (Docusaurus), <%= vars.name %> (Zensical, macros extension with ERB delimiters), {% $vars.name %} (Starlight), {name} (Antora). The book’s template_variables.yml, or its successor, stays the one place values are written. Zensical’s ERB delimiters: Accepted (Docs WG lead, 2026-10-11).
  2. The build writes each tool’s variables from that file: text as text; empty values as ""; values that hold HTML or Markdown in the form the tool renders inline (JSX; a Markdoc tree; HTML; as written). Values that are blocks become partials. Keys only layouts read go to the site’s configuration; title is never an AsciiDoc attribute; the key that is not a name is dropped. Whether the source is one file or one shared folder of several files (fewer values reached by one editor’s mistake) is decided at implementation (Docs WG lead, 2026-10-11).
  3. Every site requires every name at build: Docusaurus through its variables module, Zensical with on_undefined = "strict", Starlight with a validator run in make build, Antora with attribute-missing: warn and failure_level: warn. Accepted (Docs WG lead, 2026-10-11), with a note that Starlight’s validator runs outside the tool; a check of variables outside every tool may be worth having as well.
  4. References to undefined and empty names are removed before conversion, each listed in the cleanup record (82 uses on 59 names); they render as nothing today (R-24 markup cleanup before conversion). Accepted (Docs WG lead, 2026-10-11): the list stays with the Docs WG, which does the conversion, rather than going to page owners. The list, with the empty keys to remove as well: cleanup.md.
  5. Each place has a rule per tool, as in Each place a variable can sit: code blocks keep their type; link targets use the tool’s link form; titles and descriptions take the value where front matter cannot hold a variable; in Docusaurus, the site’s heading plugin writes a heading’s variable as its value before the table of contents is made (tested 2026-10-11, in place of hand-written tables of contents). After convention 9 few such headings remain.
  6. Code that only computes text is evaluated by the converter: the title line of all_metrics and the two conditions on the stacks pages become their result, listed for the owners.
  7. The variables check runs on every converted page, beside the outline and notes checks: checks/vars.py, with a variables file per page; and a browser check where the tool builds content in the browser (checks/vars-browser.mjs).
  8. The copyright year is not a variable: it stays with the copyright concept (R-25 build-time values are expected differences).
  9. Product names are written as text: “Cloud Foundry”, “CF” and “cf” from app_runtime_abbr and the eleven other keys (Product names). Accepted (Docs WG lead, 2026-10-11).

Requirements

Not yet written