cf-docs-rfc-proposal

Partials round — results

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

Summary

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

Docusaurus 3.10.2

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

Summary

Grid

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.

Zensical 0.0.69

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

Summary

Grid

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          

Starlight 0.42.6

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

Summary

Grid

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          

Antora 3.2.1

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

Summary

Grid

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          

Across tools

Where a call sits

The survey found four calls that are not on a line of their own, all in list items (survey):

Headings, ids and the table of contents

Partials in other repositories

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.

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

How a partial reads in the source

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

Are partial names in variables still needed?

The research area asks whether a page must still be able to pick its partial from a variable (research area). Evidence from this round:

  1. No page does it. Ten values in the book’s variables name a partial file; no page at the surveyed commits uses any of them, and every partial they name is included by its literal name (survey).
  2. It served two editions. The form came in to let one source include a different partial in the open-source and the commercial book (“moving partials into variables to remove commercial refs in OSS”, 2018). Literal names replaced it from 2023; the last change to such a call is dated 2024-08-20. The commercial branches were removed in July 2026, when the repositories came to serve “only the OSS Cloud Foundry doc set” (survey).
  3. Tools differ exactly here. Zensical and Antora take a name from a variable directly; Docusaurus needs JavaScript in the page; Starlight cannot, except through a condition that lists every partial (grids above). A requirement to keep the form would rule out, or add code to, two of the four tools for a feature with no user.

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.

Conventions to record

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

  1. A partial becomes a file of the tool’s own format, included with the tool’s own include (native mode): an imported MDX component (Docusaurus), the template engine’s include (Zensical), the Markdoc partial tag (Starlight), include::partial$…[] (Antora).
  2. Where partial files live: beside their pages with the leading underscore kept, _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.
  3. The converter’s rule for each call form in the book: <%= 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.
  4. A partial after text in a list item goes on its own line under the item, after the text, which stays the item’s first paragraph. Accepted (Docs WG lead, 2026-10-11).
  5. A partial that is a list step’s content is placed inside the step: the include indented under the item (Docusaurus, Starlight), wrapped in filter indent(N) (Zensical), or after {empty}, + and inside an open block (Antora).
  6. A partial name held in a variable is resolved at conversion time; no converted page takes a partial’s name from a variable (recommendation). Accepted (Docs WG lead, 2026-10-11).
  7. Headings in partials carry explicit ids in the tool’s syntax, as on pages (headings round), and a partial with headings is not included twice on one page; the partials check fails on an id used twice inside an included span.
  8. The build fails on a missing partial: Zensical with 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.
  9. The partials check runs on every converted page that includes a partial, beside the outline and notes checks: checks/partials.py.

Requirements

Not yet written