Status: draft, incomplete — covers what is known as of 2026-10-11.
What each tool did with the test pages’ partials. A summary across tools comes first, then one section per tool, then the cases across tools, a recommendation on partial names held in variables, and the conventions to record. How the pages were chosen and what the modes mean: README. Per-page intent: intent/. How the book writes and resolves partials: 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).
Every tool renders every partial in the right place, with its headings, lists, notes, tables and variables, in both passthrough and native, once the call sits on a line of its own. They differ in what a call next to text needs, whether a partial’s name can come from a variable, and what the build says when something is wrong.
| Docusaurus | Zensical | Starlight | Antora | |
|---|---|---|---|---|
| Partials check, native | 6 of 6 | 6 of 6 | 6 of 6 | 6 of 6, the table of contents checked in the browser |
| Partials check, passthrough | 6 of 6 | 4 of 6: step 5’s last paragraph leaves the list, as published; table of contents uses generated ids | 6 of 6 | 6 of 6, the table of contents checked in the browser |
| Include | import X from './_x.mdx' and <X /> |
<% include "native/_x.md" %> (template engine); --8<-- snippets render no variables |
{% partial file="./_x.mdoc" /%} |
include::partial$x.adoc[] |
| Call after text in a list item | builds; React hydration error #418 in the browser | builds; label and text joined in one paragraph | the build stops: “‘partial’ tag should be block” | not possible; the directive starts a line |
| Partial that is a whole list step | 1. <X /> |
filter indent(4) around the include |
1. {% partial … /%} |
. {empty}, +, open block |
| Headings in a partial in the table of contents | yes | yes | yes | yes (built in the browser) |
| Same partial twice: explicit id | twice, no message | twice, no message | twice, no message | twice, with a warning naming partial and page |
| Nested partial | yes | yes (snippets: no) | yes | yes |
| Partial in another content source | @site/shared/…, no configuration |
must sit under include_dir; snippets take a list of folders |
a relative path out of the content folder, no configuration | include::shared::partial$…[], another component |
| Name from a variable | only through page code (a map, require, a condition) |
<% include "native/_" ~ vars.scale_table ~ ".md" %> |
no: “Could not read partial file [object Object]”; a condition works |
include::native::partial${scale_table}.adoc[] |
| Missing partial | build fails; names the folder, not the page | build fails; names neither | build fails; names the page | error in the log with page and line; exit status 0 unless --log-failure-level is set |
| ERB call as written | does not compile | build fails | text on the page | text on the page |
_tcp_modify_ports, the whole of a list step, loses its last paragraph
to the space after the list on the published page, and the “On this
page” list leaves out every heading a partial holds:
using-vol-services has an empty one
(published check;
survey). In
Docusaurus, Starlight and Antora, and in Zensical native, the paragraph
stays in the step and the headings are in the table of contents.
Treated as defects (Docs WG lead, 2026-10-11): the converted pages fix them.<%= partial '…' %> with a literal name, none in a conditional, none
with locals:, none crossing a repository, no nesting, and four in list
items (survey). The converter’s rules are
correspondingly few (Conventions).Site: sites/docusaurus/ — conventions: CONVENTIONS.md.
* **Log Cache:** <LogCache /> builds, and the static HTML splits the
label and the partial’s paragraph; React then reports error #418, a
hydration mismatch, on load (browser check).
Native puts the partial on its own line under the item: no error.#modify-ports, #migrate;
build warnings).require with a template string, or a condition.| Mode | high-availability | architecture | enabling-tcp-routing | troubleshoot-app-health | routes-domains | using-vol-services |
|---|---|---|---|---|---|---|
| passthrough | ok | ok; React #418 in the browser | ok | ok | ok | ok; toc ok |
| native | ok | ok | ok | ok (shared partial) | ok (shared partial) | ok; toc ok; nested |
| variable | map, require, condition: ok | |||||
| raw | does not compile |
“ok” is the partials, outline and (where the page has notes) notes checks.
Site: sites/zensical/ — conventions: CONVENTIONS.md.
indent filter and keeps it in the step.""), and an include folder that holds
the virtual environment made the build hang
(conventions).| Mode | high-availability | architecture | enabling-tcp-routing | troubleshoot-app-health | routes-domains | using-vol-services |
|---|---|---|---|---|---|---|
| passthrough | ok | ok | step 5’s last paragraph after the list | ok | ok | toc links to generated ids |
| native | ok | ok | ok | ok (shared partial) | ok (shared partial) | ok; toc ok; nested |
| snippet | variable left as ERB | variables left as ERB | ok | variable left as ERB | variable left as ERB | variables and nested include left as ERB |
| variable | include with an expression: ok |
|||||
| raw | build fails |
Site: sites/starlight/ — conventions: CONVENTIONS.md.
| Mode | high-availability | architecture | enabling-tcp-routing | troubleshoot-app-health | routes-domains | using-vol-services |
|---|---|---|---|---|---|---|
| passthrough | ok | ok (partial moved below the label) | ok | ok | ok | ok; toc ok |
| native | ok | ok | ok | ok (shared partial) | ok (shared partial) | ok; toc ok; nested |
| variable | condition: ok; file=$vars…: build stops |
|||||
| raw | ERB call shown as text |
Site: sites/antora/ — conventions: CONVENTIONS.md.
partials/ folder,
included by resource id; another component’s by its name. The relative
include of a file beside the page works but is deprecated.include::native::partial${scale_table}.adoc[].--log-failure-level is set
(probe).| Mode | high-availability | architecture | enabling-tcp-routing | troubleshoot-app-health | routes-domains | using-vol-services |
|---|---|---|---|---|---|---|
| passthrough | ok | ok | ok | ok | ok | ok; toc in the browser |
| native | ok | ok | ok | ok (shared component) | ok (shared component) | ok; toc in the browser; nested |
| variable | attribute in the path, condition: ok | |||||
| raw | ERB call shown as text |
The survey found four calls that are not on a line of their own, all in list items (survey):
architecture, three calls). Today the book
publishes <p><strong>Log Cache:</strong> <p>…</p></p>, which a browser
shows as two paragraphs. No tool takes the call as written without a
cost: Starlight and Antora cannot, Docusaurus builds a page that errors
in the browser, Zensical joins label and text into one paragraph.
Decision (this round): the label stays the item’s first paragraph, the
partial follows on its own line under it. That reproduces the published
look in every tool and passes every check.enabling-tcp-routing). The tools that
read a partial as a document of its own (Docusaurus, Starlight) keep all
of it in the step. The textual includes (Zensical’s template engine,
Antora) need the partial’s lines placed inside the item: Jinja’s
indent filter, or AsciiDoc’s + and open block.No partial call in the book crosses a repository today; the 25 that did pointed at the commercial edition’s folders and were removed in July 2026 (survey). Every tool can reach a partial outside the page’s content tree: Docusaurus and Starlight by import path, Zensical by putting the files under its include folder, Antora by component name. Which of these fits depends on where the content lives after migration (R-08 cross-repository links), not on the partials.
Every tool notices a missing partial at build time. Docusaurus, Zensical and Starlight fail the build; Antora logs an error and succeeds unless its failure level is set, and then shows “Unresolved include directive” on the page. Starlight and Antora name the page; Docusaurus names its folder; Zensical names neither. The book, through Middleman, fails the build and goes on rendering the other pages (survey).
The same call, high-availability’s, as each tool writes it:
<%= partial 'oss_scale_table' %>
import OssScaleTable from './_oss_scale_table.mdx';
<OssScaleTable />
<% include "native/_oss_scale_table.md" %>
{% partial file="./_oss_scale_table.mdoc" /%}
include::partial$oss_scale_table.adoc[]
Zensical, Starlight and Antora write one line where the source has one, with the file’s name in it. Docusaurus writes two, far apart, and names the file only in the import (R-11 readable source).
The research area asks whether a page must still be able to pick its partial from a variable (research area). Evidence from this round:
Recommendation, accepted (Docs WG lead, 2026-10-11): partial names in variables are not needed. The converter resolves any such name when it converts and writes a plain include, and the ten unused variables are removed from the book’s variables file in the cleanup before conversion (R-24 markup cleanup before conversion; list: cleanup.md). If a second edition returns, each tool’s own mechanism (an attribute in Antora, an expression in Zensical, a condition in the others) can be chosen then.
For cf-docs-migrate convert. Decisions of this round, for review:
include (Zensical), the Markdoc
partial tag (Starlight), include::partial$…[] (Antora)._name.mdx (Docusaurus) and _name.mdoc (Starlight);
under partials/ outside docs/ (Zensical); the module’s partials/
folder without the underscore (Antora). The source’s _name.html.md.erb
loses .html.md.erb for the tool’s extension.<%= partial 'name' %> and "name" alike; ./name and ./dir/name
relative to the page; ../<directory>/name resolved through the book’s
config.yml to the repository and file it names today. A call on a
line of its own becomes the tool’s include on a line of its own.filter indent(N) (Zensical), or after {empty}, + and inside an
open block (Antora).on_error_fail (and check_paths if snippets are used), Antora with
--log-failure-level=error; Docusaurus and Starlight do by default.
Accepted (Docs WG lead, 2026-10-11), for CI as well.""._c2c_oss_*, _oss_credhub, _oss_xfcc_*, _old_collector,
_go_tcp_routers_health_check_oss); only _using-vol-services was
converted. The probe used _old_collector’s heading../metrics/… partials in a subfolder (all_metrics, eight calls):
resolved by the survey, not converted. Relative links inside a partial
resolve against the including page in the book; that was not tested in
the tools.require
form when the variable names no file, were not tested.docs-bosh snippets (two SVG diagrams) were counted, not converted.