cf-docs-rfc-proposal

Concept: Partials

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:

Progress

Test pages

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.

Partials check

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:

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).

Method

  1. Survey every partial call and partial file, and how the book resolves a name.
  2. Choose pages that hold the patterns, preferring pages already converted.
  3. Write the intent: where each partial’s content must appear.
  4. Convert by hand into each tool, every mode; the content outside the includes follows the earlier rounds’ conventions.
  5. Build and check with the partials, outline and notes checks, the probes, and a browser.
  6. Record conventions per tool (sites/<tool>/CONVENTIONS.md).

Each tool keeps the version and configuration of the earlier rounds; Zensical turns on pymdownx.snippets for its snippet mode.

Layout

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.