Status: draft, incomplete — covers what is known as of 2026-10-10.
This document describes the tools evaluated for the Cloud Foundry documentation, the input formats they read, how today’s pages are converted into them, the extensions each tool needs, and the problems found on the way. It is neutral evidence: it describes what was built and seen, and makes no choice. Every tool’s status is “under evaluation”; Hugo and VitePress are “not yet assessed”.
Parts:
Requirements are cited by ID and a short phrase, for example “R-03 column widths as hints”. The IDs and their full statements are in requirements/. Terms are defined where they are first used; the glossary has more on each.
The CF documentation today is written as .html.md.erb files. Each mixes
three things: Markdown (plain text with light formatting marks such as #
for headings), HTML (the markup language of web pages) and ERB tags
(<%= … %>, Ruby code that fills in variables and includes other files
when the site is built). The test pages (published pages with complex tables that the Docs
WG lead chose for testing tools; listed below) are examples
(sources). Bookbinder, a Ruby
command-line tool that “stitch[es] together” Markdown repositories into one
site (gemspec),
collects these files. The list of repositories is in
config.yml
in the book, the repository
docs-book-cloudfoundry
that holds the site’s settings and layout. Bookbinder hands the files to Middleman
(gemspec),
a Ruby static site generator (a program that turns source files into a set
of web pages).
RFC #1642 (the draft proposal for a new CF docs stack) asks for Markdown authoring and, in the same list, for the ability to handle HTML:
Ability to handle HTML, especially HTML tables with column-width specification supported
The working framing for this evaluation is that the input needs simple text formatting and HTML injection: plain text for most of a page, and HTML where plain text cannot say what the page needs (R-10 simple text plus HTML where needed). Whether a tool can do that is a property of the tool and of the format it reads, so the tools have to be looked at before the content can be planned. Decision (evaluation framing): the format is open; Markdown is one candidate, not a requirement.
The first test was tables, because complex HTML tables are the main reason the content is not plain Markdown today: 123 of the book’s 195 tables are HTML (this evaluation’s table survey, 2026-10-09). The Docs WG lead picked five pages whose tables are hard to express outside HTML; that choice is an input to this evaluation. They are listed in concepts/tables/README.md. The full record of that round is under concepts/tables/; this document summarises it and links to it.
Not every tool got the same amount of work. The tiers come from concepts/README.md:
| Tier | Tools | What was done | Status |
|---|---|---|---|
| Hands-on | Docusaurus, Zensical, Starlight (on Astro), Antora | All five test pages converted by hand in every mode (below), built, measured in a browser, and checked | under evaluation |
| Probe | Eleventy, Sphinx with MyST, Middleman without Bookbinder | One question each, with only the pages it needs: Eleventy two test pages, Sphinx one table, Middleman all five test pages | under evaluation |
| On paper | Hugo, VitePress | A capability check against the requirements is planned | not yet assessed |
A probe is a small test that answers one question in one tool. Each tool’s entry, with its findings, is in tools.md.
Each test page was converted into each hands-on tool in several ways, called modes. A mode is a choice of how much of the source’s HTML to keep:
A hint is what a table asks for, written once and independent of any tool.
The hints are a column’s role (key for a short label, value, or prose
for sentences), a width, whether a column avoids wrapping, whether the
first column holds row headers, and a title. Hints express intent, not exact values;
each tool honors them as well as it can (R-03 column widths as hints). The
full list: Hints after the round.
What every mode looks like for one table: formats.md.
How a page gets from today’s source into a tool’s input. What the migration as a whole involves (inventory, owners, redirects, cutover) is in requirements/migration.md; this section is the “how”.
RFC #1642 asks for one conversion done centrally (L131):
The conversion MUST be done by one central migration team to ensure consistency, not by each Working Group individually.
The plan is to record, concept by concept, the conversion rules that worked
when pages were converted by hand. Later they are built into a migration
tool, cf-docs-migrate, with a scan command (find every instance of a
concept across the docs) and a convert command (apply the rules)
(R-23 one central conversion). The tool is not yet written. A concept is one kind
of thing the pages contain, such as tables, variables or code blocks; the
list is in concepts/README.md.
The steps seen in the tables round, in order:
<col>, an unclosed cell, a class
written with typographic quotes, a row closed with </td>). Browsers repair this silently;
tools that read HTML strictly do not (R-24 markup cleanup before
conversion). The defects are listed in
Markup that only browsers tolerate.<%= vars.name %> and
<%= partial '…' %> become each tool’s syntax (R-04 variables everywhere,
R-05 partials and reuse). The forms are listed per tool in
tools.md.The headings round proposes its conversion rules as conventions, under review (headings results), and so do the notes, variables and partials rounds (notes, variables, partials).
Not yet written: the conversion steps for the other concepts
(code blocks, cross-repository links), and how
scan and convert are built.
No tool’s own table syntax carries every hint. The column roles and the capped no-wrap (a column that stays on one line up to a limit the template sets, then wraps between words) need CSS in every tool. What else each tool needed, as built in the tables round:
| Tool | What its own syntax lacks | What closes the gap | Code written |
|---|---|---|---|
| Docusaurus | widths, row headers, top alignment, title row, roles, no-wrap | a remark plugin (code that changes the Markdown before it becomes HTML): plugins/list-table.js | JavaScript, 94 lines today, plus CSS |
| Zensical | row headers, title row, roles, no-wrap (widths go on header cells) | a Python-Markdown block: list_table.py | Python, 120 lines today, plus CSS |
| Starlight | row headers, top alignment, title row, roles, no-wrap | attributes added to Markdoc’s own table tag: list-table.mjs | JavaScript, 83 lines today, plus CSS |
| Antora | roles, no-wrap | roles (class names) on the AsciiDoc table, given meaning by a stylesheet: hints.css | CSS only for the hints; an 8-line script puts wide tables in a scrolling box |
| Sphinx with MyST (probe) | roles, no-wrap | classes on the list-table, given meaning by a stylesheet |
CSS only |
| Eleventy (probe) | nothing: the HTML is used as written | the official EJS plugin | none |
| Middleman (probe) | nothing: the pages build unchanged | a short config file and a layout | none |
Variables that hold HTML need care in three tools. MDX (Docusaurus),
Markdoc (Starlight) and EJS (Eleventy) escape a variable’s value, so a value
such as <p class="note">…</p> shows as text unless the page uses a
special form for it. Zensical, Antora and Middleman insert the value as
markup, as the published site does.
RFC #1642 L100 says:
Working Groups MUST NOT need custom extensions, plugins, or JavaScript code to author documentation.
Whether one shared extension, maintained once for all documentation, meets that line is a requirements question (R-13 no per-WG extensions), not a tooling one. The table above shows what each tool needed for the test pages.
Problems found in the tables round that a conversion must handle. Most sit outside the tables and belong to concepts not yet worked; they are listed here because they stop a page from building or change its content.
| Problem | Tools affected | Requirement | Evidence |
|---|---|---|---|
| Markup that only browsers tolerate breaks the build or changes content | Docusaurus (MDX), Starlight (Markdoc) | R-24 markup cleanup before conversion | summary |
Text inside HTML is read as Markdown: a lone - becomes a list, spaces next to tags disappear, */* loses its * — with no error |
Starlight (Markdoc); Docusaurus (MDX) for */* |
R-01 content and outline survive | Starlight findings |
Braces {…} in prose are code in MDX |
Docusaurus | R-01 content and outline survive | raw passthrough errors |
| HTML-valued variables are escaped | Docusaurus, Starlight, Eleventy | R-04 variables everywhere | Eleventy probe |
| Every page rewritten in another format, with silent failures | Antora | R-01 content and outline survive | Antora finding 1 |
| Themes style different tables: all, only classless ones, only their own | all four | R-09 table styles by class | summary |
Heading anchors written <a id> break the table of contents |
Docusaurus | R-16 old URLs keep working | Docusaurus finding 6 |
| A page description shows raw variable code | Docusaurus | R-20 search-engine and AI-friendly output | Docusaurus finding 7 |
HTML notes damaged without a warning: an empty note box, words run together, >= as a blockquote |
Docusaurus, Starlight | R-07 notes and admonitions | notes results |
| A note never closed swallows the rest of the page or stops the build | Zensical, Docusaurus, Starlight | R-24 markup cleanup before conversion | notes never closed |
| No check for links to missing anchors | Starlight, Antora | R-08 cross-repository links (a link checker is how broken links are found) | Starlight finding 7 |
| ERB tags shown as examples in prose are run as code | Zensical (its template engine reads every <%= … %>) |
R-01 content and outline survive | Zensical finding 3 |
| A table after a list step leaves the list unless indented | Docusaurus, Zensical, Starlight | R-01 content and outline survive | Docusaurus finding 3 |
| Default themes hyphenate words in cells | Antora, Sphinx | none yet (a template choice) | Antora finding 5 |
Not yet written: problem areas for the concepts not yet worked (code blocks, cross-repository links), and for the two tools not yet assessed.