cf-docs-rfc-proposal

Tools

Status: draft, incomplete — covers what is known as of 2026-10-10.

Each tool considered for the CF documentation: what it is, what it reads, what was done with it, what was seen, and the concerns the evidence shows. No tool has been chosen or rejected. Every tool’s status is “under evaluation”, except Hugo and VitePress, which are “not yet assessed”.

A static site generator is a program that turns source files (text, templates, settings) into a folder of web pages that any web server can host. Every tool below is one, or a documentation theme on top of one.

Requirements are cited by ID and a short phrase; the full list is in requirements/. Modes (raw passthrough, passthrough, extension, native, native-plain) are defined in the Tooling README. Each input format, with the same table written in it, is in formats.md.

Terms used on this page:

Summary

Tool Reads Tier Version tested License Status
Docusaurus MDX, Markdown hands-on 3.10.2 MIT under evaluation
Zensical Markdown (Python-Markdown) hands-on 0.0.69 MIT under evaluation
Starlight Markdoc (as set up here), Markdown, MDX hands-on 0.42.6 on Astro 7.3.8 MIT under evaluation
Antora AsciiDoc hands-on 3.2.1 MPL-2.0 under evaluation
Eleventy Markdown run through a template language (EJS here) probe 3.1.6 MIT under evaluation
Sphinx with MyST MyST, reStructuredText probe Sphinx 9.1.0, MyST parser 5.1.0 BSD-2-Clause; MyST parser MIT under evaluation
Middleman ERB, Markdown, HTML probe (without Bookbinder) 4.6.3 on Ruby 4.0.7 MIT under evaluation
Hugo Markdown, Go templates on paper — Apache-2.0 not yet assessed
VitePress Markdown, Vue components on paper — MIT not yet assessed

Each license links to the project’s license file at the commit checked on 2026-10-10 (R-19 open source only). Tiers are explained in the Tooling README.

Across the four hands-on tools, the round found that every test table renders correctly in every mode once the source is cleaned up. The tools differ in how much cleanup the HTML needs, which hints their own table syntax carries, and how much of the rest of the page must change (results summary).

Formats tested

Each tool was run in one of the formats it reads: Docusaurus in MDX, Zensical in Python-Markdown, Starlight in Markdoc, Antora in AsciiDoc, Eleventy in Markdown with EJS, Sphinx in MyST, and Middleman in today’s ERB pages. The other formats in the “Reads” column are untested, among them Docusaurus’s CommonMark mode for .md files (turned on in this site’s docusaurus.config.js, but no test page uses it), Starlight’s Markdown and MDX, and Sphinx’s reStructuredText. Running Starlight with Markdoc was not a recorded decision.

Decision (2026-10-10): every tool is to be tested in each format it reads. Not yet done.

Today’s stack

Bookbinder

What it is. A Ruby command-line tool that “stitch[es] together” Markdown repositories into one site (gemspec). It reads the book’s config.yml in docs-book-cloudfoundry, collects the docs-* content repositories it names, and builds them into one site with Middleman (a runtime dependency in its gemspec). Each repository maps to a fixed URL directory (the directory: of its section in config.yml), so a page’s URL names the repository and file to edit (R-15 URL identifies the source). Learn more: Bookbinder; see also the glossary.

What was seen. Its repository’s last commit is dated 2024-10-17 (checked 2026-10-10). The Middleman probe built all five test pages without it, and every table matched the published page: Bookbinder adds nothing the tables need. What else the book’s build does (collecting repositories, navigation, the “Page last updated” line) was not tested without it.

Status. In use today. RFC #1642 proposes replacing the stack it is part of (Problem, L17–25).

Hands-on tools

Each was built with all five test pages (and a sixth for the table-style example) in every mode, with versions pinned, and checked with the shared spot checks, a word-by-word comparison with the published page, and a browser check for wide tables. Each site folder has a CONVENTIONS.md with the patterns that worked.

Docusaurus

What it is. A static site generator for documentation, built on React (a JavaScript library for building pages; React and MDX are dependencies of its core package). Pages are Markdown or MDX: Markdown in which HTML is read as JSX, React’s stricter HTML-like syntax. Learn more: Docusaurus; see also the glossary.

RFC #1642 names it (L31):

The recommended engine is the current major version of Docusaurus (v3 or newer, maintained by Meta, MIT-licensed, widely adopted in the CNCF ecosystem).

What was done. Docusaurus 3.10.2, default theme. Site: sites/docusaurus/; results: results.md.

Result. None of the five pages builds with its HTML unchanged; three of the five first errors are outside the tables. After cleanup every table renders correctly in all three modes. Its own table syntax is the pipe table, which carries no widths, row headers or titles.

Concerns, with evidence:

Variables and partials. One import vars line per page, then {vars.name}. A partial (a file included in other pages) is imported and used as a component, which answers RFC L179 (“Are partials supported by Docusaurus?”) for the scale table: yes, as an MDX import. R-05 partials and reuse.

Status: under evaluation.

Zensical

What it is. A static site generator for documentation from the team behind Material for MkDocs (the project’s own description: README). Pages are Markdown read by Python-Markdown (the markdown package is a dependency). Learn more: Zensical; see also the glossary.

What was done. Zensical 0.0.69, default theme. Site: sites/zensical/; results: results.md.

Result. All five pages build with their HTML unchanged, and the variables keep their <%= vars.name %> form. With the intent files’ cleanup and one indent, every spot check passes in every mode. Native pipe tables carry widths on header cells; row headers, the title row and the capped no-wrap need HTML or the extension, a Python-Markdown block (list_table.py).

Concerns, with evidence:

Variables and partials. Variables as written, through Zensical’s template engine set to ERB-style tags; HTML values render as markup. Partials need the template engine’s include; the --8<-- snippet include does not fill in the partial’s variables (finding 7).

Status: under evaluation.

Starlight

What it is. A documentation theme for Astro, a JavaScript static site generator (Astro is a peer dependency). In this evaluation its pages are Markdoc (.mdoc): Markdown with {% %} tags, with HTML allowed, read through Astro’s Markdoc integration. Learn more: Starlight, Astro; see also the glossary.

What was done. Starlight 0.42.6 on Astro 7.3.8, Markdoc integration 2.0.11, default theme. Its Markdown and MDX pages are untested (Formats tested). Site: sites/starlight/; results: results.md.

Result. Four of the five pages parse with their HTML unchanged. Markdoc’s own {% table %} tag holds lists and paragraphs in cells and widths on header cells without custom code; row headers, top alignment, a title row and the capped no-wrap need the extension, which adds attributes to that same tag (list-table.mjs). The theme styles every table, and the site’s CSS wins over it without extra work.

Concerns, with evidence:

Variables and partials. {% $vars.name %}; partials with {% partial file="…" /%}, and their variables render.

Status: under evaluation.

Antora

What it is. A static site generator for documentation written in AsciiDoc, a plain-text format with its own table syntax. It is designed to build one site from content in several repositories: the playbook’s content key is a list of content sources, and the project’s README calls it a “single or multi-repository site generator”. Learn more: Antora; see also the glossary.

What was done. Antora 3.2.1, with its default UI (the theme) pinned to one build. Site: sites/antora/; results: results.md.

Result. HTML tables build unchanged inside AsciiDoc passthrough blocks. AsciiDoc’s own table carries widths, content-sized columns, a header row, row headers, top alignment, spanning cells, and lists and paragraphs in cells. The extension needs no code: roles (class names) on the table and a stylesheet. Every spot check passes in every mode.

Concerns, with evidence:

Variables and partials. Variables are AsciiDoc attributes, {name}; an undefined one shows as text unless attribute-missing: drop is set. HTML values render as markup. Partials with include::partial$file.adoc[].

Status: under evaluation.

Probes

Each probe answered one question in one tool and built only what the question needed: Eleventy two test pages (uaa-concepts and the scale-table partial), Sphinx with MyST one table (the scale table), and Middleman all five test pages.

Eleventy

What it is. A JavaScript static site generator that runs pages through a template language before Markdown. Here the template language is EJS, whose tags look like ERB’s. Learn more: Eleventy; see also the glossary.

Question. Do <%= vars.* %> tags render unchanged as EJS?

Answer. Yes for the tables: uaa-concepts and the scale table come out byte for byte as written. EJS’s <%= escapes HTML, so HTML-valued variables, helpers and includes need <%-, and an include needs the full file name. EJS is a plugin since Eleventy 3: Eleventy 2.0.1 depends on ejs, 3.0.0 does not, and the @11ty/eleventy-plugin-ejs package adds it back. Details: probes/eleventy.

Concerns. The Middleman helpers other than partial (image_tag, link_to) have no EJS counterpart; not covered. A literal <% in prose must be written <%%, as in ERB. R-04 variables everywhere, R-05 partials and reuse.

Status: under evaluation.

Sphinx with MyST

What it is. Sphinx is a documentation generator from the Python world; the MyST parser lets it read MyST, Markdown with directives (named blocks with options). The parser is a Sphinx extension built on markdown-it-py (dependencies). Learn more: Sphinx, MyST parser; see also the glossary.

Question. Can a MyST list-table’s directive options carry the table hints?

Answer. Mostly yes, with no code. Header row, row headers and widths are options; the column roles and the capped no-wrap are classes on the table, given meaning by a stylesheet. All five spot checks pass. A second header row (a title above the column headers) is not carried. Details: probes/sphinx-myst.

Concerns. The default theme hyphenates words in cells (turned off in the stylesheet). Inline code is rewritten into one <span> per word, which a text comparison has to undo. The probe covered one table only.

Status: under evaluation.

Middleman

What it is. A Ruby static site generator; the one Bookbinder runs today. The book pins bookbindery 9.12.1 (Gemfile), which depends on Middleman 3.4 (RubyGems; the repository has no 9.12.1 gemspec, and its last 9.12.0 gemspec asks for ~> 3.4.0); the latest Bookbinder source depends on Middleman 4.1.10. Learn more: Middleman; see also the glossary.

Question. What is the smallest change that removes Bookbinder and keeps the pages’ ERB and HTML?

Answer. A short config file (the book’s Markdown settings and its vars helper) and a small layout. All five pages build unchanged on Ruby 4.0.7 (plus the ostruct gem), every table matches the published page cell for cell, and variables and the partial behave as in the book. Details: probes/middleman.

Concerns. This keeps ERB and Ruby. RFC #1642 lists among the MUST capabilities (L39) “A lightweight templating/component system that does not require Ruby or ERB”. Whether that line stands is a requirements question. The probe’s layout has none of the book’s navigation; search, versioning and the rest of the site were not tested.

Status: under evaluation, as the minimal-change baseline.

Not yet assessed

Planned as on-paper capability checks against the requirements. Nothing has been built.

Hugo

What it is. A static site generator written in Go. Pages are Markdown, read by the goldmark parser (go.mod); shortcodes and Go templates add what Markdown lacks. RFC #1642 names it as an alternative that “MAY be evaluated” (L31). cloudfoundry/what-is-cf is a Hugo site today: its deploy script runs hugo. Learn more: Hugo; see also the glossary.

Not yet written: the capability check (tables and hints, variables in cells, partials, local preview, search, versioning).

Status: not yet assessed.

VitePress

What it is. A static site generator built on Vite and Vue (JavaScript tools). Pages are Markdown read by markdown-it, and can use Vue components (dependencies, markdown-it). Learn more: VitePress; see also the glossary.

Not yet written: the capability check, as for Hugo.

Status: not yet assessed.

Other tools in the CF docs today

Not yet written: whether bosh.io and the API references are in scope for the new stack; that is a requirements question.

Passed over

Things set aside during the evaluation. Each entry says what was done, why it was set aside, where the evidence is, and what would change the decision. These are recorded because the reasons may be wrong.

MkDocs with Material for MkDocs

What was done: not built. MkDocs (BSD-2-Clause; last commit dated 2025-10-20, checked 2026-10-10) had its license checked, and bosh.io’s MkDocs Material site was read and its tables surveyed (Other tools in the CF docs today).

Why: No separate decision was recorded. RFC #1642 L31 names MkDocs as an alternative that “MAY be evaluated”. Zensical, a hands-on tool here, comes from the team behind Material for MkDocs (README) and reads mkdocs.yml (config.py), so the round tested the Markdown reader MkDocs also uses, Python-Markdown, but not MkDocs itself.

Evidence: bosh.io is built with MkDocs and Material for MkDocs (above). On the RFC pull request, a community member reports that Concourse moved from Booklit to MkDocs Material and then to Zensical (comment).

What would change it: a reason to keep MkDocs itself rather than Zensical, such as bosh.io staying on it, or a question from the Docs WG.

Generators not placed in a tier

What was done: only read about. mdBook (MPL-2.0), Jekyll (MIT), Nextra (MIT) and Docsy, a Hugo theme (Apache-2.0), had their licenses checked. None was built.

Why: Decision (evaluation scope, 2026-10): the evaluation was kept to the likely candidates, the tools already tried out by the people working on the CF docs. These four did not come up as candidates; Jekyll, for example, was never proposed. Leaving them out was a choice of scope, not a finding against them; any of them could be added now.

Evidence: none in this repository yet; the license links above.

What would change it: a requirement one of them meets better than the tiered tools, or a question from the Docs WG.

Width variants A and B

What was done: the six tables on troubleshooting_slow_requests were built three ways in Docusaurus: A as written, B with uniform widths (25/25/50), C with no widths so the column roles decide.

Why: C was chosen after the renderings were compared. The six tables share one Result / Explanation / Action shape, and the template convention that came out of the round is that widths follow the column roles (key, prose) where a table’s widths carry no other intent (R-03 column widths as hints).

Evidence: width variants, with screenshots of table 2 in each.

What would change it: pages where roles alone size columns badly, or an owner who needs the exact source widths.

A table title as a caption or a spanning row

What was done: the metadata title was built as a spanning row above the column headers, as a caption, and as a bold line above the table.

Why: Markdown and Markdoc tables have one header row, so a spanning title row pushes the column headers into the body (R-02 rich tables). The bold line above the table was kept. Passthrough keeps the source’s spanning row.

Evidence: side by side; Starlight finding 4.

What would change it: a format chosen for every page that has two header rows, or owners who need the title inside the table.

Joining HTML table cells onto one line for Markdoc

What was done: putting each cell on one line keeps the spaces Markdoc otherwise drops next to inline tags; tried in Starlight passthrough.

Why: not adopted as a general conversion rule, because it makes the source harder to read (R-11 readable source). It is used only where Markdoc would change the text.

Evidence: Starlight summary.

What would change it: a Markdoc version that keeps those spaces, or a decision that passthrough source readability matters less than a uniform rule.

Typographic quotes in Starlight

What was done: the Markdoc integration’s typographer setting was turned on.

Why: besides prose, it changes quotes inside <pre> blocks and HTML <code>, which changes content, so the setting was left off (R-01 content and outline survive).

Evidence: Starlight finding 9.

What would change it: a setting that applies only to prose.

Eleventy’s default template language

What was done: not tried. The probe ran its Markdown pages through EJS; Eleventy’s default for Markdown is Liquid (defaultConfig.js at v3.1.6).

Why: the probe’s question was whether today’s <%= vars.name %> tags can stay as they are. EJS uses the same tags; Liquid writes {{ … }}, so every variable would have to be rewritten (R-04 variables everywhere).

Evidence: probes/eleventy.

What would change it: a conversion that rewrites the variables in any case, which would make the tag shape no reason to pick EJS.

Typographic quotes in Zensical

What was done: not tried. Zensical’s quotes stay straight, while the published book shows typographic ones (user’s). Python-Markdown’s smarty extension would make them typographic; it is not turned on.

Why: not tested in the tables round. Starlight’s equivalent setting also changed quotes inside <pre> and <code> (Typographic quotes in Starlight), so the result would need checking (R-01 content and outline survive).

Evidence: Zensical, text compared with the published page.

What would change it: a test showing that smarty changes prose only.

Snippet includes for partials in Zensical

What was done: the scale-table partial was included with a --8<-- snippet.

Why: the template engine’s include is used instead. A snippet is inserted after variables are filled in, so the partial’s <%= vars.recommended_by %> showed as text (R-05 partials and reuse).

Evidence: Zensical finding 7.

What would change it: a snippet option that runs before variables are filled in.