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 a page that includes a partial renders the partial’s content in the right place, with its headings, lists, notes, tables and variables intact, in each hands-on tool, and what each tool needs for the ways the book uses partials (R-05 partials and reuse). It also gathers data for the open question whether a page still needs to pick its partial from a variable (research area), and adds a partials check beside the outline and notes checks.
Terms used below:
_name.html.md.erb and includes it with <%= partial 'name' %>, an ERB
call (ERB is the Ruby template language the book’s pages are written
in). The tools call the same thing a partial, a snippet, or an imported
component.docs-*
repositories and the book repository at the notes survey’s commits: 45
calls in content, 7 in the book’s layout, 48 partial files, and how
Bookbinder and Middleman resolve a name, with pinned source lines.
History back to 2016 for the partial names held in variables.
Script, data and write-up: survey/.| Page | Repository | Partials | Cases |
|---|---|---|---|
high-availability, one section |
cloudfoundry/docs-cloudfoundry-concepts | _oss_scale_table |
the partial whose name the book also holds in a variable (scale_table); a table and a variable in the partial; converted in the tables round |
using-vol-services, the notes round’s excerpt |
cloudfoundry/docs-dev-guide | _using-vol-services, and in native the note partial inside it |
a page that is only a partial call; headings with ids inside a partial; a nested partial; notes in the partial |
architecture, two sections |
cloudfoundry/docs-loggregator | _log_cache (twice), _syslog_agents |
a partial after text in a list item; the same partial twice on one page; variables in a partial |
enabling-tcp-routing, one section |
cloudfoundry/docs-cf-admin | _tcp_modify_ports, and in native the note partial mutual_tls_tcp |
a partial that is a whole list step; a path through the section’s folder name; a note held in a variable |
troubleshoot-app-health and routes-domains, one section each |
cloudfoundry/docs-dev-guide | _routing_conflict |
the one partial included from two pages; in native, kept in another content source |
How they were chosen. Decision (this round): from the survey’s rows,
few pages that together hold the common case (a call on a line of its own)
and every other pattern the book has: the four calls in list items, the
two partials included more than once, the one page that is only a call,
the largest partial with headings, and a partial whose name a variable
holds. Two pages come from earlier rounds (high-availability’s partial
from tables, using-vol-services from notes); routes-domains is the
headings round’s page, in another section. Patterns the book does not have
were tested where they matter for migration: a partial’s name from a
variable (variable mode), a nested partial (made by the notes round’s
convention for notes held in variables), a partial in another content
source, and a partial with a heading included twice (a probe). No page
has locals:, a call inside a conditional or a call in a table cell; the
survey found none.
checks/partials.py reads a built HTML page and checks each partial against a partials file. It needs only Python 3.
# The page's text blocks, with section and place, any include syntax left, and the table of contents
python3 -I checks/partials.py published/architecture.html
# A built page against its partials file
python3 -I checks/partials.py BUILT.html --expect intent/architecture.partials
# All three checks on every page in some modes of one site (run from sites/<tool>, after make build)
../../checks/check-site.sh build note=note,important=warning,caution=danger passthrough native variable
What it does:
<%, {% partial,
include::, --8<--, an MDX import, “Unresolved directive”.toc line names, in the
static HTML: Docusaurus, Zensical, Starlight and the published book’s
quick links. Antora builds its table of contents in the browser;
partials-browser.mjs reads it there and
records console errors.It knows nothing about these pages. make check in each site runs it with
the outline check (with each page’s anchors) and, on the two pages with
notes, the notes check. Run on the published pages, it fails twice, on the
book’s own defects (published check).
<tool>/CONVENTIONS.md).Each tool keeps the version and configuration of the earlier rounds;
Zensical turns on pymdownx.snippets for its snippet mode.
concepts/partials/
├── README.md this file
├── results.md results per tool, cases, recommendation, conventions
├── survey/ partial survey: survey.py, summary.py, calls.csv, partials.csv, shas, README
├── source/ new test pages and partials, verbatim, plus SOURCES.md
├── published/ the four new published pages, as served on 2026-10-11
├── intent/ per page: <page>.md, <page>.partials (what the check reads), <page>.anchors; one .notes
├── checks/ partials.py, check-site.sh, partials-browser.mjs
├── sites/ docusaurus/, zensical/, starlight/, antora/: pages per mode, config, Makefile, CONVENTIONS.md
└── results/ check output per tool, build warnings, probes, browser check, published check
Each site builds with make build and checks with make check; make
check-probe and make probe-missing run the probes. 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.