cf-docs-rfc-proposal

Code blocks round — results

Status: draft, incomplete — covers what is known as of 2026-10-11.

What each tool did with the test pages’ code blocks. A summary across tools comes first, then one section per tool, then the cases across tools, the conventions to record and the questions for the Docs WG lead. How the pages were chosen and what the modes mean: README. Per-page intent: intent/. How the book writes and renders code blocks: survey.

How to read the results:

All checks ran on 2026-10-11 against the published pages saved that day and the earlier rounds’ copies, with the tool versions the earlier rounds pinned (Docusaurus 3.10.2, Zensical 0.0.69, Starlight 0.42.6 with @astrojs/markdoc 2.0.11, Antora 3.2.1 with the default UI).

Summary

In native mode every tool keeps every code block: 53 of 53 blocks with their exact text, their type and a working copy button, in the right section and place, on all seven pages (checks). Passthrough shows what the book’s own forms cost: between 31 and 45 of the 53 blocks pass, and <pre> blocks lose their copy button and type in every tool.

  Docusaurus Zensical Starlight Antora
Blocks that pass, native 53 of 53 53 of 53 53 of 53 53 of 53
Blocks that pass, passthrough 31 of 53 41 of 53 45 of 53 45 of 53
A code block in the source a fence a fence a fence [source,TYPE] and ----
Highlighter Prism, at build time Pygments, at build time Shiki (Expressive Code), at build time highlight.js, in the browser
console highlighted only with a one-line alias in an ejected theme file yes no: one colour yes
Copy button on by default, drawn in the browser a theme feature to turn on, drawn in the browser on by default, in the static page on by default, drawn in the browser
What it copies from a console block the whole text the whole text the whole text the commands only, prompts removed, joined with &&
A variable in a code block <CodeBlock> with a template literal as written, <%= vars.name %> a fence, with eight lines of site code subs=attributes+ on the block
A <pre> block as written read as Markdown: <p> inside, */* lost, --- becomes a rule kept, but broken into paragraphs where it has a blank line in a list item the build stops on a blank line in a list item; with &#10;, inline Markdown still read kept, in a passthrough block
The book’s odd fences read as CommonMark some as the book reads them, some neither way read as CommonMark as the converter reads them
Problems the build reports none none the stop above none

Docusaurus 3.10.2

Site: sites/docusaurus/ — conventions: CONVENTIONS.md.

Summary

Grid

Blocks that pass, of each page’s blocks; in native, the blocks highlighted and what the copy buttons copied.

Mode routes-domains troubleshooting gsg-grails backup backup-clean nginx multiple-processes
passthrough 2/9 7/11 2/5 2/4 1/4 11/13 6/7
native 9/9 11/11 5/5 4/4 4/4 13/13 7/7
native, highlighted 9 9 4 4 4 11 3
native, copies text text text text text text text

Zensical 0.0.69

Site: sites/zensical/ — conventions: CONVENTIONS.md.

Summary

Grid

Mode routes-domains troubleshooting gsg-grails backup backup-clean nginx multiple-processes
passthrough 7/9 10/11 4/5 2/4 2/4 11/13 5/7
native 9/9 11/11 5/5 4/4 4/4 13/13 7/7
native, highlighted 9 7 3 3 4 12 1
native, copies text text text text text text text

Starlight 0.42.6

Site: sites/starlight/ — conventions: CONVENTIONS.md.

Summary

Grid

Mode routes-domains troubleshooting gsg-grails backup backup-clean nginx multiple-processes
passthrough 8/9 10/11 5/5 3/4 1/4 11/13 7/7
native 9/9 11/11 5/5 4/4 4/4 13/13 7/7
native, highlighted 1 9 3 4 3 12 5
native, copies text text text text text text text

Antora 3.2.1

Site: sites/antora/ — conventions: CONVENTIONS.md.

Summary

Grid

Mode routes-domains troubleshooting gsg-grails backup backup-clean nginx multiple-processes
passthrough 8/9 11/11 5/5 1/4 2/4 11/13 7/7
native 9/9 11/11 5/5 4/4 4/4 13/13 7/7
native, highlighted 9 5 3 2 2 1 1
native, copies commands commands 3, text 8 commands 2, text 3 text commands 2, text 2 text text

Across tools

What a copy button copies

Three tools copy the block as shown. From a console block that is the prompts and the output too, which a reader pasting into a terminal has to remove. Antora’s default UI copies only the commands. The book has no copy button today (survey), and its pages already split most commands from their output: a fence with the command and its placeholders, then a <pre class="terminal"> example with a prompt and output (gsg-grails, troubleshooting_slow_requests, backup-clean). A reader copies the first and reads the second. Which behaviour the docs want is question 1.

Type names

Type Prism (Docusaurus) Pygments (Zensical) Shiki (Starlight) highlight.js (Antora UI)
console no grammar, unless aliased to shell-session session: prompt lines as commands, other lines as output session, in one colour session (the shell grammar)
bash script script script script
shell script script script session: lines without a prompt are not highlighted
yaml, json yes yes yes yes
nginx added by the site yes yes no grammar
text no colour no colour no colour no colour

So commands without a prompt are bash and sessions console in every tool. The book’s 164 console fences without a prompt (survey) are drawn as output by Pygments and Prism; native writes them bash. Sources:

<pre> blocks

The book writes 592 <pre> blocks. Kept as HTML, no tool gives them a type, highlighting or a copy button, and two tools change their text:

Native mode makes every <pre> a fence (or a source block), which every tool handles alike. That is proposed convention 1.

The book’s odd fences

The survey found 14 files where the book’s Markdown engine and CommonMark find different code blocks. Four are on the test pages:

Case The book (published) Docusaurus, Starlight Zensical Antora (through pandoc)
fence right after a line of text (backup L64) inline code code block code block code block with the list’s indentation in its text
fence closed by ```<br> (backup L74) block, ended by the list item block that runs on not a code block code block with the list’s indentation in its text
four backticks closed by three (backup L359) block block that runs on and takes the <pre> inline code block that runs on
fence indented four under a paragraph of three (multiple-processes L20) block that shows the fence lines YAML block block that shows the fence lines YAML block

No reading is right for every case, and no build reports any of them. The fix is in the source, before conversion (proposed convention 5; R-24).

Variables in code

Each tool writes the variables round’s native form, and in native mode all 8 blocks with variables on routes-domains show their values. One change from that round: Starlight’s Expressive Code fences need the site’s fence node, eight lines, because the preset passes the raw text.

Template delimiters and character references

What the builds report

None of the passthrough failures above shows in any build log: Docusaurus reports broken links and anchors, Zensical missing anchors, Antora section levels, Starlight nothing (build warnings). The one exception is Starlight’s stop on a blank line inside a <pre> in a list item. The code-block check is what finds them.

How a code block reads in the source

The same block, routes-domains’ TCP route, in each tool’s native form:

```console
$ cf create-route example-space tcp-domain.example.com --port 60035
```
[source,console]
----
$ cf create-route example-space tcp-domain.example.com --port 60035
----

Docusaurus, Zensical and Starlight write the same fence; with a variable inside, Docusaurus writes <CodeBlock> and the others keep the fence (R-11 readable source).

Conventions to record

For cf-docs-migrate convert. Decisions of this round, for review:

  1. Every code block becomes the tool’s own code block with a type: a fence in Docusaurus, Zensical and Starlight, [source,TYPE] in Antora. <pre class="terminal">, <pre> and <pre><code> become fences; no <pre> HTML is left on a converted page.
  2. Type names: console for a session with $ prompts (and its output); bash for commands without prompts and for shell scripts; yaml, json, xml, nginx and the other languages by their names, lower case (yml becomes yaml, c# csharp); text for output, logs and anything else. Never shell, which highlight.js reads as a session.
  3. A block with no type, or a console block without a prompt, gets one from its text: a first line with $ is console; a YAML or JSON file is yaml or json; one or more commands are bash; anything else is text. Each type the converter chooses is listed for the page’s owners (question 2). Accepted (Docs WG lead, 2026-10-11), with text as the fallback.
  4. A code block’s text is the published block’s text, without the list item’s indentation, and with the published page’s defects fixed: markup shown as text (<span>@</span> in a fence), character references written in a fence, fence lines shown in a block, blocks broken into paragraphs, and fences published as inline code. Each fix is listed (question 3). Accepted (Docs WG lead, 2026-10-11).
  5. The book’s odd fences are repaired before conversion (R-24): a blank line before a fence that follows text, closing fences that match their opening, fences indented to their list item, <pre> not indented four spaces at the top level; the 14 files are in the survey, and each fix is in cleanup.md.
  6. A variable inside a code block uses each tool’s form: as written (Zensical), subs=attributes+ on the block (Antora), <CodeBlock> with a template literal (Docusaurus), and the site’s fence node that fills in variables (Starlight).
  7. Every site has copy buttons and the highlighting the types need: Zensical turns on content.code.copy; Docusaurus adds Prism’s bash, shell-session and nginx grammars and the console alias; the others as they come. What a console block’s button copies follows question 1: each tool’s default, accepted (Docs WG lead, 2026-10-11).
  8. The code-block check runs on every converted page, in the build and in the browser: checks/codeblocks.py with a code file per page, and checks/codeblocks-browser.mjs for copy buttons and highlighting drawn in the browser.

Questions for the Docs WG lead

  1. What should a copy button copy from a console block? Background: Docusaurus, Zensical and Starlight copy the whole block, prompts and output included; Antora’s default UI copies the commands only. The book has no copy button today, and its pages mostly put the command in one block and the sample session in the next. Question: is copying a session’s text, prompts and all, acceptable? Recommendation: accept each tool’s default for now. Commands a reader runs are in bash blocks, which every tool copies whole; changing what three tools copy from console blocks would be site code (R-13). Answer (Docs WG lead, 2026-10-11): accepted; each tool’s default.
  2. May the converter choose types? Background: 807 fences have no type, 592 <pre> blocks have none, and 164 console fences hold commands without prompts, which Pygments and Prism draw as output. Question: should the converter type them from their text (convention 3), listing each choice for the owners? Recommendation: yes, with text where no rule fits. Answer (Docs WG lead, 2026-10-11): yes, with text as the fallback.
  3. Are the published code-block defects defects? Background: five of seven test pages show markup, character references or fence lines as text, break blocks into paragraphs, or publish a fence as inline code; the survey finds the same patterns elsewhere. Question: may the converted pages fix them, as the partials round’s accepted decision did for its defects? Recommendation: yes, each fix listed (convention 4). Answer (Docs WG lead, 2026-10-11): yes, each fix listed.
  4. Starlight’s one-colour console blocks. Background: Shiki’s shell session grammar does not tokenize the command. Question: accept, or ask that Starlight be judged without it until the grammar changes? Recommendation: accept and record; the text, type and copy button are right, and the other three tools highlight console. Answer (Docs WG lead, 2026-10-11): accepted and recorded.

Requirements

Not yet written