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:
<pre> on a built page and compares it with the page’s
code file (intent/): its text exactly (after dropping
trailing white space and blank lines at the ends), its section and
place (body, list item, note, table), no template syntax or markup
shown in it, and no block elements (<p>, <hr>, list items) made
inside it. It also reads the type the block declares, whether it is
highlighted, whether it has a copy button and what that button copies.
“53 of 53” means every block on the seven test pages passes.<pre> blocks as HTML;
native writes every block as the tool’s own code block with a type,
and fixes the published page’s defects. Everything outside code blocks
is the same in both modes and follows the earlier rounds’ native
conventions.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).
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 , 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 |
<pre> blocks do not survive as HTML. Docusaurus and Starlight
read the text inside HTML as Markdown; Zensical passes the block
through, but Python-Markdown splits it at a blank line in a list item,
as the book’s engine does; Antora keeps it in a passthrough block. In
every tool a <pre> has no type, no highlighting and no copy button.
592 of the book’s 1,777 blocks are <pre> blocks
(survey).shell as a terminal session and highlights only
lines with a prompt; Prism, Pygments and Shiki read it as a script.
Pygments and Prism show a console line without a prompt as output.
bash and console mean the same in all four.Site: sites/docusaurus/ — conventions: CONVENTIONS.md.
<CodeBlock> (browser check).console grammar. A ```console block gets no
tokens; one line in an ejected copy of the theme’s
prism-include-languages.js makes console a name for Prism’s
shell-session (probe). Docusaurus
marks that file as meant to be ejected.<pre> text is read as Markdown. All six <pre>
blocks on routes-domains hold <p> elements; Accept: */* loses its
asterisks; a YAML file’s --- becomes <hr> and - mysql a list item
(check). The book’s CommonMark-only
fences become blocks, and its unclosed ones swallow what follows..md page loses its <pre>
elements (probe).<code>{{port}}</code> in prose stops the build when the page
renders, “ReferenceError: port is not defined”
(raw check); both modes write it as
inline code.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 |
Site: sites/zensical/ — conventions: CONVENTIONS.md.
<%= vars.name %>
(browser check).<pre> that holds a <code>, and copies the text as shown.console line without a prompt as output, so
native writes such blocks bash.<pre>
with a blank line in a list item, the way the book’s engine does, and
shows < as written (check). It reads
the other odd fences its own way: a fence right after text is a code
block, a fence closed by ```<br> is none, four backticks
closed by three are inline code. A <pre class="terminal"> passes
through with its text, but with no type or copy button.| 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 |
Site: sites/starlight/ — conventions: CONVENTIONS.md.
console blocks have one colour: Shiki’s shell session grammar
does not split the command into tokens
(probe).<pre> with a blank line in a list item stops the
build (raw check); written with
, the earlier rounds’ form, the text survives except for inline
Markdown (*/*). Unlabelled fences are plaintext with a copy button.| 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 |
Site: sites/antora/ — conventions: CONVENTIONS.md.
[source,TYPE], with
subs=attributes+ where it holds a variable
(browser check).console block’s commands only: each $
line without its prompt, backslash continuations joined, the commands
joined with ` && `. Other blocks copy their text.shell as a session, so native writes commands
without prompts as bash; the UI’s highlight.js has no NGINX grammar,
so none of the 11 nginx blocks has a colour.<pre> blocks are kept in passthrough blocks, with no
type, highlighting or copy button; unlabelled fences become literal
blocks, which get a copy button only when their first line starts with
$ . The prose was converted with pandoc, so the book’s odd fences come
out as pandoc’s CommonMark reader reads them
(check).| 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 |
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 | 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:
sh and shell names for bash
(prism-bash.js L233-L234)
and has a shell-session grammar, not console
(prism-shell-session.js L68);
Prism 1.30.0.shell to its
bash lexer
(shell.py L31)
and console to its session lexer
(L230),
which marks a line without a prompt as output
(L214).shell to its shell-script grammar
(shellscript.mjs)
and console to its session grammar
(shellsession.mjs),
@shikijs/langs 4.5.0; the probe shows
the session grammar’s one token.shell with the alias console
and a rule that highlights only a line with a prompt
(js/vendor/highlight.js in the pinned UI bundle, whose URL and
SHA-256 are in the Makefile).<pre> blocksThe 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:
*/*
becomes emphasis, --- a rule and - item a list. Starlight stops the
build on a blank line inside a list item, and with each line break
written still reads inline Markdown. These are the tables
round’s findings, now on every kind of <pre>
(tables results).<pre> with a blank line in a list item, as the book’s
Redcarpet does.Native mode makes every <pre> a fence (or a source block), which every
tool handles alike. That is proposed convention 1.
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).
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.
{{…}} in a fence is safe in every tool (nginx: five blocks).
Zensical’s ERB delimiters, accepted in the variables round, leave
{{ alone. In Docusaurus prose, <code>{{port}}</code> stops the
build; backticks do not.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.
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).
For cf-docs-migrate convert. Decisions of this round, for review:
[source,TYPE] in
Antora. <pre class="terminal">, <pre> and <pre><code> become
fences; no <pre> HTML is left on a converted page.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.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.<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).<pre> not
indented four spaces at the top level; the 14 files are in the
survey,
and each fix is in cleanup.md.subs=attributes+ on the block (Antora), <CodeBlock>
with a template literal (Docusaurus), and the site’s fence node that
fills in variables (Starlight).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).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.<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.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.bash rather than shell (Antora), a console
alias (Docusaurus), and is not there for console in Starlight or
nginx in Antora.<pre> blocks are where the book’s HTML costs most; a
fence replaces each.console alias (one line in an ejected file) and
Starlight’s fence node (eight lines) are site code the Docs WG would
keep.class=‘terminal’ attributes, the character
references in fences.<pre> in a note
was converted (gsg-grails); the four <pre><code> blocks in table
cells (_c2c_oss_enable) and the second note (gsg-spring) were not.<pre> with HTML inside other than <span>@</span>: 58 blocks
hold <strong>, links or other elements; none was converted.<br> between steps
(gsg-grails Step 9) were not converted or counted.