cf-docs-rfc-proposal

What the PoC must cover

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

What RFC #1642 asks

Phase 2, L119–127:

A PoC SHOULD be established in a new repository (e.g., cloudfoundry/docs-next) to:

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 the findings add, line by line

A representative subset, migrated to Markdown

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:

MDX alone (L104)

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.

Local development, search and versioning

GitHub Pages deployment

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.

The domain redirect strategy

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.

Feedback from contributors

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.

What else the PoC needs to cover

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.