Status: draft, incomplete — covers what is known as of 2026-10-10.
This folder compares what the candidate documentation tools did with real Cloud Foundry pages: the text an author writes in each tool next to the page the tool builds from it, and next to the page as published today. It describes; it does not recommend.
A proof of concept (PoC, or POC) is a small working build made to show whether an approach works (see the glossary).
RFC #1642, the draft proposal for a new CF docs stack, plans its PoC as Phase 2:
A PoC SHOULD be established in a new repository (e.g.,
cloudfoundry/docs-next) to: (L119)
Stand up Docusaurus (or the chosen alternative) with a representative subset of CF documentation migrated to Markdown. (L121)
The work here is smaller and comes earlier. It is not that PoC. Each candidate tool has its own small test site. The test pages (five pages the Docs WG lead picked because their tables are hard to express outside HTML, plus one added later) are converted by hand into every site, one documentation concept (one kind of content, such as tables) at a time. The question for each concept is how each tool handles that content, and at what cost. The results can inform what the Phase 2 PoC runs.
The RFC also says what its PoC must check for complex pages:
The PoC MUST validate that the most complex existing pages (HTML tables, CSS layouts) can be represented with MDX alone. Any gap found MUST be reported as a PoC finding. (L104)
The Docusaurus results here bear on that line. MDX is Markdown that also accepts JSX, the HTML-like syntax of React components (see the glossary; the MDX project’s own description). Docusaurus’s native and passthrough modes (defined below) both use MDX with no plugin.
Four tools were tried in full. Three more were probes: each answers one narrow question instead of the full round.
ERB (Embedded Ruby) is the <%= … %> tag syntax today’s pages use for
variables and partials (shared files included into a page). Middleman is the
site builder under Bookbinder, the tool that builds docs.cloudfoundry.org
today: the book
sets public_host: docs.cloudfoundry.org
and pins bookbindery 9.12.1,
which requires middleman ~> 3.4.0.
The Middleman probe is the smallest-change baseline. Hugo and
VitePress are assessed on paper only and have no results here.
| Tool | Version | Input format | How far |
|---|---|---|---|
| Docusaurus | 3.10.2 | MDX | every test page, every mode |
| Zensical | 0.0.69 | Markdown read by Python-Markdown | every test page, every mode |
| Starlight (on Astro 7.3.8) | 0.42.6 | Markdoc: Markdown with {% %} tags |
every test page, every mode |
| Antora | 3.2.1 | AsciiDoc | every test page, every mode |
| Eleventy | 3.1.6 | EJS: <% %> tags, close to today’s ERB |
two test pages: uaa-concepts and the scale-table partial (probe) |
| Sphinx with MyST | 9.1.0, 5.1.0 | MyST: Markdown with directives | one table (probe) |
| Middleman without Bookbinder | 4.6.3 | today’s ERB pages unchanged | the five original test pages (probe) |
The method is described in full in the tables concept. In short, for each test page:
Each site’s CONVENTIONS.md records the patterns that worked, for a
conversion tool to apply later
(Docusaurus,
Zensical,
Starlight,
Antora).
The tables concept is done, with open items. Input and output, page by page: tables.md. Each table as published next to the four tools’ output, side by side, in the mode you pick: comparison. Two outputs of one table, each side chosen on its own, with their inputs below: two side by side. The table families from the survey, with candidate styles: table families. Full grids, measurements and findings: results.md.
What the round found:
| between cells) take none.Four pages were converted in the four hands-on tools, in three modes each. Every heading tree survives in every tool and mode, checked by an outline check that compares each built page’s headings with the published page. Every id the source writes survives in passthrough and native; with no ids written, 11 of the 69 anchors to keep survive. The conventions are under review (headings results).
Four pages’ 16 notes were converted in the four hands-on tools, kept as HTML and written as each tool’s own admonition. Every note survives in both, checked by a notes check that compares each note’s kind, title, words, contents and place with the published page. The tool’s own admonition passes with no workaround; HTML notes pass only after changes per tool, and as written two tools damage them without a warning. A note held in a variable becomes a partial. The map from the book’s kinds to each tool’s types is still open (notes results).
Five pages’ 85 variable uses were converted in the four hands-on tools. In each tool’s own variable form every value appears in its place, in prose, code, headings, links, table cells, notes and the page title. With the book’s syntax kept, Markdown values show as text in three tools. By default no tool reports a variable that is not defined. Each can be made to, Starlight only through a check run beside the build (variables results).
Six pages that include partials were converted in the four hands-on tools. With each tool’s own include every partial renders in its place, its headings in the table of contents. A partial placed after text in a list item, as the book places four, breaks in every tool; on its own line below the text it works. No page today picks its partial through a variable (partials results).
The book computes two values at build: the footer’s copyright year and the “Page last updated” date, a Git date. Four pages were built in the four hands-on tools with three year rules (build, site, page); every tool prints each rule and shows a date written in the page. After conversion, each tool’s own Git-based date shows the conversion commit, or nothing. A date written by the converter and updated from Git, skipping listed commits, is right in all four. A comparison helper masks these values. The year follows content: the newest content year on the site, as the Docs WG lead decided on 2026-10-11 (build-time values results).
Four pages from three repositories, which link to each other, were
converted in the four hands-on tools. The repositories were laid out as
separate content sources and as one repository with directories. With
pages published at the book’s <path>.html URLs, every link reaches its
page and anchor in every tool and layout. The book’s own relative links
also work in three tools. With each tool’s default folder URLs, about two
thirds break. Docusaurus, Zensical and Antora report some broken links at
build time; Starlight does not. A survey found 55 links already broken in
the book
(cross-repository links results).
Seven page excerpts with 53 code blocks were converted in the four
hands-on tools. Written as each tool’s own code block with a type, every
block keeps its exact text, its type and a working copy button in every
tool, checked by a code-block check that compares each block with the
published page. Kept as the book writes them, HTML <pre> blocks lose
their type and copy button everywhere, and two tools change their text.
The tools differ in highlighting (console needs an alias in Docusaurus
and has one colour in Starlight) and in what a copy button copies (Antora
copies only the commands). Five published pages show code-block defects
that the converted pages fix
(code blocks results).
Every concept in Concepts now has a round.
These come from the tables round but are about the pages as a whole.
Builds with the HTML as written (five test pages):
| Docusaurus | Zensical | Starlight | Antora |
|---|---|---|---|
| none: MDX stops on all five; three of the five first errors are outside the tables | all five | four of five; Markdoc changes some text inside HTML without an error | all five, inside passthrough blocks; the page around them is rewritten as AsciiDoc |
Spot checks after cleanup (seven pages, 51 checks): Docusaurus 49 of 51 in every mode (the two misses are page descriptions, not tables); Zensical, Starlight and Antora 51 of 51 in every mode.
Text comparison, outside the tables:
| Difference | Docusaurus | Zensical | Starlight | Antora |
|---|---|---|---|---|
Accept: */* in terminal output |
shows as Accept: / |
kept | shows as Accept: / |
kept |
| Other prose | matches | three literal * where a list follows a text line |
matches after the passthrough changes | matches after the AsciiDoc rewrite |
| Quotes | straight (published: curly) | straight | straight | apostrophes curly in AsciiDoc text, straight in HTML blocks; double quotes straight everywhere |
Details: results.md, section “Text compared with the published page” under each tool.
Of the RFC’s Phase 2 items, local preview is covered in part: every site builds and serves with one command, and what a contributor installs differs by tool (what the PoC must cover). Every tool shows a wide table in its own scrolling box; Antora needed a short script for it (results summary).
Not yet written: the other Phase 2 items (search, versioning, GitHub Pages deployment, redirects, contributor feedback) were not compared across these sites.