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:
| 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).
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.
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).
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.
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:
<br />), write
style as a JavaScript object, add <tbody> and <colgroup>, escape
{…} in prose. Some of these only show as browser errors
(conventions).
R-24 markup cleanup before conversion, R-11 readable source.<div dangerouslySetInnerHTML={{__html: vars.name}} /> to render as
markup (conventions).
R-04 variables everywhere.Accept: */* shows as
Accept: / (finding 8). R-01
content and outline survive, R-06 typed code blocks.<a id> cause a browser error on every page
that has them and fail the anchor check; Docusaurus’s own {#id} form
avoids both (finding 6). R-16
old URLs keep working.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.
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:
class. Tables that
keep class="table" lose the theme’s look until the site’s CSS repeats
it (finding 1). R-09 table
styles by class.<%= … %> on a page is run, including ERB shown as an example
in prose or code. A bad one replaced the page with an error message while
the build reported success, until on_error_fail = true was set
(finding 3). Pages that
document ERB need escaping. R-01 content and outline survive.- for an empty list-table cell drops a cell with no error;
it is written - <!-- -->
(finding 5). R-01 content and
outline survive, R-11 readable source.* on one page
(text compared).
R-01 content and outline survive.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.
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:
- in a code span becomes an empty list. The
space next to an inline tag disappears when the cell spans lines
(“passwordrefers”, 19 places on one page). A blank line inside <pre>
in a list item stops the whole site from building
(findings 1–3). The fixes
are character entities (-,  , ) or one-line cells.
R-01 content and outline survive, R-24 markup cleanup before conversion.{% rawhtml value=$vars.name /%}). R-04 variables everywhere.<pre> blocks too, so the option stays off
(finding 9). R-01 content and
outline survive.Variables and partials. {% $vars.name %}; partials with
{% partial file="…" /%}, and their variables render.
Status: under evaluation.
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.
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.
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.
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.
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.
Planned as on-paper capability checks against the requirements. Nothing has been built.
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.
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.
cloudfoundry/docs-bosh) is built with MkDocs and Material
for MkDocs, not Bookbinder: its
mkdocs.yml
sets the material theme, and its
build task
runs mkdocs build in the squidfunk/mkdocs-material:9.7.6 image.
MkDocs is a Python static site generator; Material for MkDocs is a
documentation theme for it (it registers as an
MkDocs theme).
Its 40 tables are plain pipe tables (counted by this evaluation at
docs-bosh commit 20a4122;
table survey, bosh.io). This was read, not built. Learn more:
MkDocs,
Material for MkDocs; see
also the glossary.*Docs tests to write the snippets, then builds the
vendored Slate
with Middleman. CredHub uses Spring REST Docs with Asciidoctor, and its
Gradle build
copies the result into the CredHub application’s static files. RFC #1642 asks who can vet the proposal for them
(L177).
Learn more: Slate,
Spring REST Docs.Not yet written: whether bosh.io and the API references are in scope for the new stack; that is a requirements question.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.