cf-docs-rfc-proposal

Proof-of-concept results

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.

What “POC” means here

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.

Tools

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)

Method

The method is described in full in the tables concept. In short, for each test page:

  1. Intent. An intent file translates what each table asks for into hints: tool-neutral statements such as “column 1 is a key column, about 20% wide, does not wrap” (R-03 column widths as hints; requirement IDs are listed in requirements). It also lists the markup cleanup the page needs (R-24 markup cleanup before conversion) and any deliberate change from the published page. Files: intent/.
  2. Convert by hand, in each mode. A mode is one way of writing the page for a tool:
    • passthrough: the page’s HTML kept, after the cleanup its intent file lists (closing unclosed tags and similar fixes) and the changes the tool forces, with variables and partials translated to the tool’s syntax;
    • extension: the tool’s extension point (a plugin or a custom block) carrying the hints;
    • native: the tool’s own table syntax with whatever width or alignment settings it offers;
    • native-plain: native with no width or alignment settings, as most authors would write it.
  3. Build. Does the page build, and what had to change first? Each site also builds the HTML exactly as written (“raw” passthrough) to record the first errors.
  4. Spot checks. Per-table checks every converted page must pass (row counts, cells present, code kept, no stray characters), listed in the intent file and run by spot-checks.sh (R-01 content and outline survive).
  5. Text comparison. A word-by-word comparison of each page’s main text against the published page, in every mode (text-diff.py). It finds changes outside the tables that the spot checks do not cover.
  6. Measure and screenshot. Column widths are measured in a browser with a 1280-pixel window, as percent of the table, first body row. Screenshots use the same window. Each tool runs its default theme (the fonts, colors, borders and spacing it ships with). Appearance is not compared; content, structure and hints are.

Each site’s CONVENTIONS.md records the patterns that worked, for a conversion tool to apply later (Docusaurus, Zensical, Starlight, Antora).

Results by concept

Tables

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:

Headings

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

Notes and admonitions

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

Variables

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

Partials

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

Code blocks

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

Other concepts

Every concept in Concepts now has a round.

Other comparisons

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.

Files