Status: draft, incomplete — covers what is known as of 2026-10-10.
A PoC (proof of concept) is a small working build that tests whether an approach works before the full migration starts. RFC #1642 plans one as its Phase 2, in a new repository. This page quotes what the RFC asks that PoC to do and adds what the tables round (the first concept of this evaluation: tables from real pages converted by hand into each candidate tool; tables concept) found that bears on it. The comparisons built in this repository are described in poc/; the tools in tools.md.
Requirements are cited by ID and a short phrase; the full list is in requirements/.
A PoC SHOULD be established in a new repository (e.g.,
cloudfoundry/docs-next) to:
- Stand up Docusaurus (or the chosen alternative) with a representative subset of CF documentation migrated to Markdown.
- Validate local development experience, search, and versioning.
- Test GitHub Pages deployment via GitHub Actions.
- Validate the domain redirect strategy.
- Gather feedback from at least three active CF documentation contributors.
The results of the PoC SHOULD be presented in a TOC / Docs WG meeting.
Two other lines set what the PoC compares and what it must report. L31:
Other frameworks such as Hugo or MkDocs MAY be evaluated and proposed as alternatives during the PoC phase.
L104:
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.
What is known. The Docs WG lead named five pages whose tables are hard to express outside HTML; they are the test pages of the tables round (list). All five were built in the four hands-on tools and in the Middleman probe (a probe is a small test that answers one question in one tool; tiers); the Eleventy probe built two of them and the Sphinx probe one table. Every table renders correctly in every tool once the source is cleaned up; the tools differ in the cost of getting there (results summary).
What it adds:
{…} outside tables, an unclosed
<br>), so a subset of simple pages would not show them
(raw passthrough errors).
R-02 rich tables.What is known. Each test page was converted in several modes, from
keeping its HTML to rewriting it in the tool’s own syntax
(modes). In Docusaurus the test tables render correctly
as HTML in MDX after cleanup (the passthrough mode), and as a list table
through a remark plugin, code that changes the page as Docusaurus reads it
(the extension mode). With Docusaurus’s own Markdown table (the native mode),
the content survives but widths, row headers, top alignment and titles do
not: the credential-types table comes out 18/82 where the source asks for
20% (grid). These are the gaps L104
asks to be reported. R-03 column widths as hints, R-13 no per-WG
extensions.
How the same table looks in every tool and mode: formats.md and poc/tables.md.
make build, make serve), with tool versions pinned.
The Middleman probe shows today’s pages previewed without Bookbinder.
What a contributor has to install differs: Node.js for Docusaurus,
Starlight, Antora and Eleventy; Python (through uv) for Zensical and
Sphinx; Ruby for Middleman. R-12 one-command local preview.Not yet tested for any candidate tool. (This repository’s own pages are published to GitHub Pages with Jekyll; that is not a candidate build.) R-14 Docs WG approves and publishes.
Not yet tested. One finding bears on it: links to a section of a page
(page.html#section) depend on heading anchors, and the tools treat
today’s <a id="…"> anchors differently. Docusaurus reports them as broken
and shows a browser error; Antora needs each one rewritten as [[id]];
Starlight generates ids that start with a dash but keeps the <a id>
working (Docusaurus finding 6,
Antora conventions,
Starlight finding 8). R-16 old
URLs keep working.
Not yet done. The “source readability” judgments in the results are the evaluators’ own, not contributors’ (how to read the grid). One table written in every format is in formats.md. R-11 readable source.
Found in the tables round and not in the RFC’s list:
| Area | Why | Requirement | Evidence |
|---|---|---|---|
| A word-by-word comparison with the published page | It found content changes the per-table checks missed (*/*, dropped spaces) |
R-01 content and outline survive | checks/, Starlight finding 2 |
| HTML-valued and undefined variables | MDX, Markdoc and EJS escape HTML values; two variables the pages use are defined nowhere and show as empty text today | R-04 variables everywhere | progress, Eleventy probe |
| Partials | Each tool includes files differently; RFC L179 asks whether Docusaurus supports them | R-05 partials and reuse | tools.md |
Code blocks in HTML (<pre class="terminal">) |
MDX and Markdoc read their text as Markdown | R-06 typed code blocks | Docusaurus finding 8 |
| Table styles named by a class | Themes disagree on which tables they style | R-09 table styles by class | template conventions |
| Wide tables | A table wider than the column must scroll in its own box, not widen the page | R-02 rich tables | results summary |
| Link checking | Two tools do not check links to missing anchors; one does not check links inside HTML | R-08 cross-repository links | Starlight finding 7, Docusaurus finding 4 |
| Page descriptions | Docusaurus publishes raw variable code in the description search engines show | R-20 search-engine and AI-friendly output | Docusaurus finding 7 |
| Build-time values | The copyright year changes on every build; comparisons must expect it | R-25 build-time values are expected differences | concepts README |
The notes round adds one area: the map from the book’s three kinds of note to each tool’s types, which is open for Docusaurus and Starlight (notes results; R-07 notes and admonitions).
The variables and partials rounds add three areas (R-04 variables everywhere, R-05 partials and reuse). The build reports a variable that is not defined (variables results). It also reports a missing partial (partials results). And a partial inside a list item renders in place (partials results).
Not yet written: PoC scope for the concepts not yet worked (code blocks, cross-repository links), and for Hugo and VitePress, which have not been assessed.