Status: Done, with open items (listed under Not yet written). The survey, the conversions and the checks are done; the decisions are recorded in the conventions. Results: results.md.
This round asks whether the book’s variables survive conversion into each hands-on tool: their value, rendered as text or as markup as the book renders it, in every place a variable appears; and whether a variable that is not defined is reported when the site builds (R-04 variables everywhere). It adds a variables check beside the headings round’s outline check and the notes round’s notes check.
Terms used below:
<%= vars.name %>,
whose text comes from the book’s config/template_variables.yml. ERB is
the Ruby template language the book’s build runs on a page before it
reads the page’s Markdown. Value: the text a key holds; it can be
plain text, a URL, HTML or Markdown. Use: one reference in a page.<%= vars.name %> written as the tool’s
own variable reference, with the book’s values as they are and the forms
the earlier rounds use; native: the tool’s own mechanism used fully,
values prepared for the tool and every name required at build; raw: a
page exactly as the book writes it, where that shows what breaks.
Everything outside the variables is the same in both modes and follows
the earlier rounds’ conventions.docs-* repositories at
the notes survey’s commits, and every key of the variables file: 1,503
variable uses of 180 names in the book, 273 keys; 28 names used but not
defined, 31 empty keys used. Script, data and write-up:
survey/.| Page | Repository | Uses | Cases |
|---|---|---|---|
app-ssh-overview |
cloudfoundry/docs-dev-guide, whole page | 5 | an HTML value inside a sentence in a table cell; a Markdown value as a paragraph; a variable in a heading; a name not defined |
routes-domains, Domains section |
cloudfoundry/docs-dev-guide (the headings and notes rounds’ page) | 50 | variables in fenced code blocks and inline code; in HTML table and header cells; two names not defined |
troubleshooting-router-error-responses, four parts |
cloudfoundry/docs-cf-admin | 5 | a variable as a link target, in a Markdown link and in an HTML href; a variable in the first sentence; a name not defined |
container-security, four parts |
cloudfoundry/docs-cloudfoundry-concepts | 16 | variables in link text; Markdown and HTML values at the end of list items; a variable in a heading |
all_metrics |
cloudfoundry/docs-running-cf, without its partials | 1 | the page title set from a variable by ERB code |
How they were chosen. Decision (this round): from the survey’s rows,
few pages that together hold every place the book puts a variable and
every kind of value: text, HTML (inline and as a note’s whole text,
the latter already tested by the notes round), Markdown, a path; in
prose, code blocks, inline code, headings, link text, link targets, table
cells, lists, notes and the page title; and names that are not defined.
routes-domains was the one page from the earlier rounds with many
variables, and was reused. The three link-target uses in the book are on
two pages, and the title set by code on one; those pages were taken for
that reason. The pages converted in part keep every heading, so the
outline check compares whole pages; the other sections’ bodies are left
out (SOURCES). What no test page holds is under
Not yet written.
checks/vars.py reads a built HTML page and checks its variables. It needs only Python 3.
# Variable syntax left on a page, and markup or Markdown shown as text
python3 -I checks/vars.py BUILT.html --names source/template_variables.yml
# The same, then every use in the page's variables file
python3 -I checks/vars.py BUILT.html --expect intent/app-ssh-overview.vars --names source/template_variables.yml
# Every check on every page and mode of one site (run from sites/<tool>, after make build)
../../checks/check-site.sh site note=note,important=important,caution=caution
What it does:
href, src, alt, title,
content, id), for variable syntax in each tool’s form: ERB <%,
MDX {vars., vars.name, Markdoc {% and $vars., Jinja
{{ name }}, AsciiDoc {name} for a name in the variables file, and
URL-encoded ERB.<a , <code>, <p …, an HTML value escaped) and Markdown shown as
text ([text](url), backticks, **, a Markdown value not rendered).<title> and first h1.
Text is compared with white space collapsed and typographic quotes made
straight.It is written to be shared: it knows nothing about these pages, which the
variables files describe. It passes on the published copies of all five
pages. make check in each site runs it, the
outline check and, on routes-domains,
the notes check, on every page in passthrough
and native (checks/check-site.sh). The browser
check records console errors (a React hydration error shows only there),
the table of contents after the page’s scripts have run, and any variable
syntax left in the page’s text.
make probe).<tool>/CONVENTIONS.md).Each tool keeps the version and configuration of the earlier rounds.
pivotal-cf/docs-book-tiledev is a commercial book), so the names
are written as text.<%= %>,
because Jinja’s {{ }} and {# #} clash with 12 lines of the book’s
content and with {#id} heading ids. Recommendation: accept.
Answer (Docs WG lead, 2026-10-11): accepted.make build and of the pull
request checks, since Astro’s Markdoc integration will not report it.
Answer (Docs WG lead, 2026-10-11): accepted, with a note. A check
of variables outside every tool may be worth having as well.concepts/variables/
├── README.md this file
├── results.md results per tool, places, undefined names, conventions
├── survey/ survey.py, summary.py, uses.csv, values.csv, shas.txt, README
├── source/ new test pages and the variables file, verbatim, plus SOURCES.md
├── published/ the new published pages, and two the survey cites, as served on 2026-10-11
├── intent/ per page: <page>.md, <page>.vars (what the check compares), <page>.anchors
├── checks/ vars.py, check-site.sh, vars-browser.mjs
├── sites/ docusaurus/, zensical/, starlight/, antora/: pages per mode, config, Makefile, CONVENTIONS.md
└── results/ check output per tool, build warnings, probes, raw checks, browser check, a partials test
Each site builds with make build and checks with make check; make
probe and make check-raw show the undefined-name settings and the raw
mode. 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-11): 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.