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:
routes-domains, the one page with notes.<%= vars.name %> as the tool’s
own variable reference, with the book’s values as they are and the
forms the earlier rounds use; native uses the tool’s mechanism fully:
values prepared for the tool, every name required at build. raw is a
page exactly as the book writes it.All checks ran on 2026-10-11 against the published pages saved that day, with the tool versions the earlier rounds pinned.
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 |
{vars.gorouter_metrics_link}
(build warnings).Site: sites/docusaurus/ — conventions: CONVENTIONS.md.
/passthrough/{vars.gorouter_metrics_link}; the description
Docusaurus writes from the first paragraph holds
{vars.appruntimeabbr}; the page title set by ERB code cannot be
written.heading-vars.js,
about 30 lines, run before Docusaurus’s own plugins) writes each text
value into its heading first, so the generated table of contents shows
the value, in both modes, and no page writes its own; a name with no
text value stops the build (probe). A
page title taken from an # … heading still shows the expression. All
27 headings with a variable in the book read a product name.# … heading with an expression shows the
value but gives the page the <title> “{vars.app_runtime_abbr} Component
Metrics” (probe).Proxy that throws: “Variable not defined:
vars.no_such_name”, with the page’s path
(probe).<%= … %> does not compile
(raw check).<tr>
straight in <table> causes a hydration mismatch, which <tbody>
fixes, as the tables round writes it
(browser check).| 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.
Site: sites/zensical/ — conventions: CONVENTIONS.md.
title. The book’s ERB code line is not Jinja and stops the build
(raw check); the converter moves the
variable into the front matter.on_undefined = "strict" stops the build on an undefined name, with
a message that names the variable and not the page. keep prints a
debug string on the page; silent and lax print nothing.{#id} on a heading
starts a comment and stops the build, and the nginx buildpack page’s
{{port}} becomes a variable, silently empty with silent
(probe). Decision (this round): keep the
ERB delimiters in native mode too.| 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 |
Site: sites/starlight/ — conventions: CONVENTIONS.md.
link tag for variable link targets, and code blocks as
fences.[metrics](../running/all_metrics.html#routing); an HTML href keeps
the tag as text; the title set by ERB code cannot be written. The build
reports none of it.variable-undefined error. A check script
run by make build reports it (probe).| 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 | — | — | — | — |
Site: sites/antora/ — conventions: CONVENTIONS.md.
title renames every page: AsciiDoc reads an attribute of
that name as the document title
(check with the key). Passthrough leaves
it out as a forced change.attribute-missing: drop
(the earlier rounds’). With warn it logs “skipping reference to
missing attribute: no_such_name” and leaves {no_such_name} on the
page; with runtime.log.failure_level: warn the build then fails
(probe).| 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.
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.
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.
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.
rx.rb L92;
not built). So the notes round’s rule (a note held in a variable becomes
a partial, accepted) fits block values only. Zensical’s include works
inline, since it inserts text before Markdown is read; not tested here.template_variables.yml), and each site’s build or the
converter writes the tool’s form from it: Markdown and HTML as JSX for
Docusaurus, as Markdown parsed by Markdoc for Starlight, as HTML for
Antora, as written for Zensical. Values that are blocks (notes, lists,
headings, table rows) become partials.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.
For cf-docs-migrate convert. Decisions of this round, for review:
{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).""; 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).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.all_metrics and the two conditions on the stacks pages
become their result, listed for the owners.app_runtime_abbr and the eleven other keys
(Product names). Accepted (Docs WG lead,
2026-10-11).<CodeBlock language>).Proxy of about 10 lines) and heading
plugin (about 30 lines), and Starlight’s config (a link tag, 3 lines that parse values) and check
script are site code the Docs WG would maintain once.<tbody> in
Docusaurus tables.max_in_flight_header, disable_custom), a list (the five role
values on roles), or a table row (r_buildpack) are on no test page.
A heading held in a variable is part of the page’s outline.configure-lb-healthcheck
L92), which the book shows as text: kept as text by Zensical as written,
rendered by the native forms of the others. Which the owners want was
not asked.</code>, the tables round’s known issue.[`enable\_service\_discovery`](…))
are on no test page.<%-.