cf-docs-rfc-proposal

Concept: Code blocks

Status: Done, with open items (listed under Not yet written). The survey, the conversions and the checks are done; the four questions are answered. Results: results.md.

This round asks whether the book’s code blocks survive conversion into each hands-on tool: their text exactly, their type with matching highlighting, and a copy button (R-06 typed code blocks). It takes up what earlier rounds left to it: <pre> blocks that MDX and Markdoc read as Markdown (tables round), code blocks in notes (notes round), fences that only the book’s Markdown engine closes (headings survey) and variables inside code (variables round). It adds a code-block check beside the outline, notes, variables and partials checks.

Terms used below:

Progress

Test pages

Page Repository Blocks Cases
routes-domains, Create a route cloudfoundry/docs-dev-guide (the headings, notes, variables and partials rounds’ page) 9 console fences with prompts and output; <pre><code> with variables and <span>@</span>; a fence indented after a list item
troubleshooting_slow_requests, whole page cloudfoundry/docs-cf-admin (the headings and tables rounds’ page) 11 unlabelled fences; <pre class="terminal"> with blank lines and */*; a terminal block with a blank line in a list item
gsg-grails, Step 5 cloudfoundry/docs-buildpacks 5 a <pre> in a note; console without prompts; a YAML file in a terminal block; e-mail addresses in code
backup, Connect to your jumpbox cloudfoundry/docs-bbr 4 a fence right after text; a fence closed by ```<br>; nested lists
backup-clean, Clean up after a failed backup cloudfoundry/docs-bbr 4 four backticks closed by three; backslash continuations
nginx, Create the nginx.conf file cloudfoundry/docs-buildpacks 13 {{…}} template syntax in code and prose; &lt;file&gt; in a fence; untyped NGINX configuration
multiple-processes, whole page cloudfoundry/docs-dev-guide 7 a fence the published page shows as text; a terminal block with blank lines and &#35; before a note in a list item

How they were chosen. Decision (this round): from the survey’s rows, few pages that together hold the common forms (unlabelled fences, console fences, <pre class="terminal">, <pre><code>), the places (top level, list item, note) and every pattern the earlier rounds handed on: <pre> text that MDX and Markdoc read as Markdown, a code block in a note, the two fences in backup that only the book closes, and variables in code. Two pages come from earlier rounds; routes-domains holds this round’s variables in code. Three cases the survey found were added for what they test: a fence right after text (backup), a fence the published page shows as text (multiple-processes), and template syntax and character references in fences (nginx). What no test page holds is under Not yet written.

Code-block check

checks/codeblocks.py reads a built HTML page and checks its code blocks against a code file. It needs only Python 3.

# The page's code blocks: type, place, highlighting, copy button, section, first line
python3 -I checks/codeblocks.py published/nginx.html

# The blocks of some sections in the code-file format, to start a code file
python3 -I checks/codeblocks.py published/nginx.html --emit --section Port

# A built page against its code file, requiring a type on every block
python3 -I checks/codeblocks.py BUILT.html --expect intent/nginx.code --require type

# Every check on every page of one site (run from sites/<tool>, after make build)
../../checks/check-site.sh site note=note,important=important,caution=caution type

What it does:

make check in each site runs it with the outline check and, on the four pages with notes, the notes check; native mode requires a type. make check-browser serves the site, loads every page in Chrome through codeblocks-browser.mjs, clicks every copy button, saves each page as the browser holds it, and runs the same checks on the saved pages, requiring a type and a copy button in native mode. Run on the published pages, the check fails on 10 blocks of five pages, the book’s own defects (published check).

Method

  1. Survey every code block, how the book renders it, and where the book’s Markdown engine and CommonMark disagree.
  2. Choose pages that hold the patterns, preferring pages already converted.
  3. Write the intent: each block’s text, type, section and place, from the published page with its defects fixed.
  4. Convert by hand into each tool, in both modes; the content outside code blocks follows the earlier rounds’ native conventions. The mechanical part (heading ids, notes, variables, and for Antora a first draft with pandoc) was done with scratch scripts; every page was then reviewed and edited by hand.
  5. Build and check with the code-block, outline and notes checks, in the static pages and in a browser; probe what each tool does with console and with the book’s forms where the build fails.
  6. Record conventions per tool (sites/<tool>/CONVENTIONS.md).

Each tool keeps the version of the earlier rounds. Two settings are new: Zensical turns on its copy button (content.code.copy), and Starlight draws fences with the code component of its Markdoc preset. Docusaurus adds Prism grammars and a console alias.

Layout

concepts/code-blocks/
├── README.md          this file
├── results.md         results per tool, cases across tools, conventions, questions
├── survey/            survey.py, book-render.rb, commonmark-render.mjs, summary.py, compare-published.py, the CSV files, README
├── source/            new test pages and the variables excerpt, verbatim, plus SOURCES.md
├── published/         the four new published pages, as served on 2026-10-11
├── intent/            per page: <page>.md, <page>.code (what the check compares), <page>.anchors; four .notes
├── checks/            codeblocks.py, check-site.sh, codeblocks-browser.mjs
├── sites/             docusaurus/, zensical/, starlight/, antora/: pages per mode, config, Makefile, CONVENTIONS.md
└── results/           check output per tool (static and browser), build warnings, probes, raw checks, published check

Each site builds with make build and checks with make check and make check-browser; make probe and make check-raw run the probes and the raw checks where a site has them. Sites serve on ports 4101–4104. Build output and installed packages are ignored by git; the results in results/ were produced from the sites built in place.

Decision (this round): 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.