cf-docs-rfc-proposal

Tooling

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.

Why tooling first

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.

Tiers

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.

Modes

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.

Conversion process

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:

  1. Clean up the markup. Five of the twelve HTML tables on the test pages are not well-formed (an unclosed <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.
  2. Translate variables and includes. <%= 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.
  3. Write each table in the chosen mode, keeping the hints the intent file for the page records. The intent files are in concepts/tables/intent/ (for example, credential-types); each one translates the source’s exact values into hints and lists the checks the converted table must pass.
  4. Convert the rest of the page if the tool does not read Markdown. Antora reads AsciiDoc, so every page is rewritten. In the tables round this was done with pandoc (a general document converter) plus a script, and the conversion failed silently in four ways (Antora finding 1).
  5. Build and check. Three checks are shared by every site, in concepts/tables/checks/. Spot checks test each table (row and cell counts, code spans, characters that must not appear). A text check compares the page word by word with the published page. A browser check confirms that a wide table scrolls in its own box. The text comparison found content changes the spot checks missed. Build-time values such as the copyright year are expected differences (R-25 build-time values are expected differences).
  6. Owner review. Each converted area is reviewed by its owner (R-26 owner review of migrated pages). This step was not part of the tables round.

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.

Extensions needed per tool

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.

Problem areas

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.