Status: draft Docs WG position, incomplete — covers what is known as of 2026-10-10.
This document says what the Docs WG is looking for in a new documentation
stack for Cloud Foundry. The Docs WG is the Cloud Foundry working group that
edits, merges and publishes the docs at docs.cloudfoundry.org (its
charter;
glossary).
Today the site is built by Bookbinder, a Ruby tool that collects pages
from the 12 docs-* content repositories listed in the book’s
config.yml into one site
(glossary). The collection is called the book,
and its settings live in
docs-book-cloudfoundry.
It is a draft position. Nothing here has been agreed by the Docs WG yet, and parts of it may be wrong. Each requirement has one of two statuses:
proposed: stated and ready to discuss.open: part of the requirement waits on a decision, named in its
statement.The requirements say what the docs need, not which tool or file format provides it. Which tools meet them is in Tooling; the side-by-side results are in POC.
RFC #1642 is a Request for Comments: the Cloud Foundry community’s process for proposing a change that affects many teams (glossary). It proposes moving the docs to Markdown on a modern static site generator (a program that turns a folder of text files into a website; glossary), hosted on GitHub Pages (GitHub’s hosting for static sites; glossary). This document is a more detailed set of requirements meant to feed that RFC.
The RFC is a draft too. Every quote from it here is exact and taken from commit
c737539 of the pull request, file toc/rfc/rfc-draft-new-cf-docs-stack.md;
each quote links to its line, as in L42. Where this document disagrees with
the RFC, it quotes the RFC and states the position next to the quote
(below).
Some points come from the RFC’s pre-review: comments on an earlier draft, made in a shared document before the pull request opened. That document is not public, so these points are labelled “non-public pre-review”; a comment on the pull request records that the pre-review took place and what it was for. Where code or a repository shows the same thing, it is cited as well.
The RFC writes MUST, SHOULD and MAY in capitals. These are RFC 2119 keywords: a requirement, a recommendation and an option (glossary). The requirements below use a plain “must”.
| Part | What it covers |
|---|---|
| This page | The requirement list, and where the RFC is wrong or incomplete |
| Audiences | Who changes the docs, who else is affected, and what each needs |
| Keep and pain | What works today and must stay; what causes problems |
| Research areas | Questions that still need an answer, and what would answer them |
| Migration | The steps from today’s book to the new site |
Each requirement has an ID and a short phrase, so “R-03 column widths as hints” can be cited on its own. IDs are never renumbered; new ones are added at the end. The other documents cite these IDs.
Terms used in the table:
<%= vars.name %> and defined in the
book’s template_variables.yml
(glossary).<%= partial 'name' %> (glossary).docs.cloudfoundry.org, the RFC’s “Phase 4: Cutover and Decommission”
(L133).| ID | Phrase | Statement | Source | Status |
|---|---|---|---|---|
| R-01 | content and outline survive | A converted page keeps its words, code, links, heading tree and section order. Content may be restructured only where its source structure was chosen for formatting, and each such change is recorded as a deviation. | Concepts principles | proposed |
| R-02 | rich tables | Tables can hold lists and paragraphs in cells, cells that span columns, row headers, a title above the column headers, and variables in cells, as the test pages do. A table wider than the page scrolls in its own box. | L42; test pages | proposed |
| R-03 | column widths as hints | An author can say how wide a column should be and whether it should avoid wrapping. The site honors this as intent, not as an exact value: a column’s role (a short key, a value, or prose) decides most widths. | L42; hints | proposed |
| R-04 | variables everywhere | Variables work in prose, in table cells, inside HTML and in page descriptions. A variable whose value is HTML renders as markup, not as escaped text. A variable that is not defined is reported when the site builds, instead of showing as empty text. | L43; variables in cells | proposed |
| R-05 | partials and reuse | A page can include a partial, and the partial renders inside it. The book can also hold a partial’s name in a variable (scale_table: "oss_scale_table"), but no page uses that form; it is not needed, and the converter resolves any such name. |
L179; _oss_scale_table |
proposed |
| R-06 | typed code blocks | Code blocks show their type (bash, console, JSON, YAML) with matching highlighting, keep their text exactly, and have a copy button. | L44; tables findings; code blocks results | proposed |
| R-07 | notes and admonitions | A note, today <p class="note"> with a note__title span, becomes an admonition (a boxed callout headed Note, Warning, and so on; glossary) with the same text, including notes held in a variable. |
Concepts list; L100 | proposed |
| R-08 | cross-repository links | Links between pages that come from different content repositories keep working after conversion, whatever the new repository layout, and the build reports a link whose page or anchor is missing. | L131; cross-repository links results | proposed |
| R-09 | table styles by class | Each table names its look with a style class (a name the site’s stylesheet gives a look to; glossary). table is the standard style. A further style is one more class and a few stylesheet rules, maintained by the Docs WG. Which further styles to offer is open. |
Template conventions | proposed |
| ID | Phrase | Statement | Source | Status |
|---|---|---|---|---|
| R-10 | simple text plus HTML where needed | Authors write most content in a simple text format and use HTML where that format falls short, as today’s pages do. The format is chosen against these requirements; Markdown is a candidate, not a given. | Concepts principles; L42; L104 | proposed |
| R-11 | readable source | An author can read and edit a page’s source, tables included, without knowing the build tool’s programming language. | Source readability | proposed |
| R-12 | one-command local preview | A contributor previews a change with one command, without installing a language toolchain by hand; a container option is offered. | L20; L38; L162 | proposed |
| R-13 | no per-WG extensions | Working groups do not write extensions (code added to the build tool so it handles markup it lacks; glossary). The Docs WG maintains shared extensions that every page can use; another working group adds one only with Docs WG approval. | L100; L104; tables results | proposed |
| R-22 | spellcheck with a shared dictionary | Every docs pull request is spellchecked against a shared project dictionary that the Docs WG maintains, so CF and technical terms can be added. | L96 | proposed |
| R-28 | onboarding before cutover | Current maintainers get time to learn the new toolchain before the new site replaces the old one. | L115 | proposed |
| ID | Phrase | Statement | Source | Status |
|---|---|---|---|---|
| R-14 | Docs WG approves and publishes | Only Docs WG approvers merge content and start publishing. The Docs WG reviews every pull request. | L54; L82; the book README and CODEOWNERS today |
proposed |
| R-17 | an owner for every area | Every documentation area has a named working-group owner, listed in a CODEOWNERS file (a GitHub file that names who must review changes to which paths; glossary), before its pages migrate. |
L75; L114 | proposed |
| R-19 | open source only | Every tool in the stack is open source. Whether this also covers services, such as a hosted search index or the hosting itself, is open. | Concepts principles | open |
| R-27 | a named owner for every task | Each task the new stack creates (migration, technical support of the build, the domain and DNS, the shared extensions, the dictionary) has a named owner before the phase that needs it. | L172; L174; L176; L178 | proposed |
| ID | Phrase | Statement | Source | Status |
|---|---|---|---|---|
| R-15 | URL identifies the source | From a page’s URL a contributor can tell which repository and file to edit. Today docs.cloudfoundry.org/<dir>/<file>.html maps to <file>.html.md.erb in the repository that the book’s config.yml assigns to <dir>. If the content moves into one repository, its directories keep that mapping. |
Docs WG lead’s comment on the RFC pull request; config.yml |
proposed |
| R-16 | old URLs keep working | Every published URL, including those the book’s redirects.rb serves today, still resolves after cutover, directly or by redirect. Heading anchors keep their ids where the conversion can keep them. |
L46; L58; L61; L137 | proposed |
| R-18 | full-text search | The site has working full-text search across all its pages. | L21; L36 | proposed |
| R-20 | search-engine and AI-friendly output | The site is plain, crawlable HTML with page titles, descriptions, canonical URLs (the one address search engines should use for a page) and a sitemap, so search engines and AI-based developer tools can read it. Whether to publish an llms.txt file (a plain-text index of the site’s pages for such tools; glossary) is open. |
L22; L40; L41 | proposed |
| R-21 | versioning | Version 1 publishes one version of the docs. How versions follow CF releases is decided later, from experience with Version 1. | L37; L92; L94 | open |
| R-29 | API docs in the same pipeline | The UAA API docs, and the CredHub API docs if they are in scope, are built and published by the same pipeline as the rest of the docs. | L13; L177; Docs WG lead, non-public pre-review; today the UAA API reference has its own build (build.gradle.kts) | proposed |
| R-30 | single-page HTML and PDF | Besides the multi-page site, each section of the docs (as the book’s config.yml divides them) can be downloaded as one large document, both as a single HTML page and as a PDF, built from the same source. One document for the whole book is wanted too, but the size of the book may rule it out. |
Decision (draft Docs WG position, 2026-10-10). Tools already offer it, for example Sphinx’s singlehtml builder and Antora Assembler’s PDF export |
proposed |
| ID | Phrase | Statement | Source | Status |
|---|---|---|---|---|
| R-23 | one central conversion | One central team converts all content the same way, with one set of rules, not each working group on its own. | L131 | proposed |
| R-24 | markup cleanup before conversion | Markup that browsers accept but strict parsers reject is fixed before, or as the first step of, conversion, and each fix is recorded. | Markup that only browsers tolerate; cleanup lists: variables, partials, links, code blocks | proposed |
| R-25 | build-time values are expected differences | When a converted page is compared with the published page, values set at build or serve time (the copyright year in the footer, the “Page last updated” date, a sitemap’s lastmod, response headers) count as expected differences and are listed apart. |
Copyright concept; build-time values results | proposed |
| R-26 | owner review of migrated pages | The owning working group reviews every migrated section before cutover. | L131 | proposed |
IDs added after the first 26 so far:
Working Groups MUST NOT need custom extensions, plugins, or JavaScript code to author documentation.
(L100)
A Docusaurus proof of concept for Stratos showed that MDX does not fully replace raw HTML. To address this, reusable MDX content (partials, snippets, and the built-in Docusaurus components) SHOULD be used instead of raw HTML, without writing custom JavaScript or React components. The PoC MUST validate that the most complex existing pages (HTML tables, CSS layouts) can be represented with MDX alone.
(L104)
Position. MDX is Markdown that can also hold JSX, the HTML-like syntax of the React library (glossary). The RFC’s own evidence at L104 says MDX alone falls short. The tables round (the first concept, worked by hand in four candidate tools: Docusaurus, Zensical, Starlight and Antora; see Tooling) found the same. Every tool needs stylesheet rules for two table hints (statements of author intent, here a column’s role and “don’t wrap”; glossary). Docusaurus, Zensical and Starlight need a small extension to carry them; Antora and a one-page test in Sphinx (a Python documentation generator; glossary) carry them as classes with no code (results). The rule should be about who writes extensions, not whether any exist. Working groups do not write their own. The Docs WG maintains shared extensions that apply across all documentation, and another working group adds one only with Docs WG approval (R-13 no per-WG extensions). Suggested wording for both lines was posted on the pull request on 2026-10-09 (L100 suggestion, L104 suggestion); as of 2026-10-10 neither has been applied.
History. The rule at L100 is recent. The RFC’s first version (commit 4dbccd9, 2025-06-30) said at L77:
The chosen framework SHOULD support a plugin or extension mechanism so that Working Groups can add custom components (e.g., interactive CLI examples, version-specific callouts) without forking the core tooling. Docusaurus MDX support covers this use case. Custom extensions MUST be documented and reviewed to avoid introducing new maintenance burdens.
Commit 3dbd2c3 (2026-10-06) replaced it with the “MUST NOT” wording
quoted above
(L97 at that commit).
The position above is closer to the first version: extensions are allowed
and reviewed, and the Docs WG owns them.
Migration effort: Converting ERB/HTML to Markdown at scale requires significant up-front work from Working Groups.
(L160)
The conversion MUST be done by one central migration team to ensure consistency, not by each Working Group individually.
(L131)
Position. L131 is right, and matches what the Docs WG lead asked for (non-public pre-review): all conversion done by the migration team, the same way for every repository. L160 should describe the central team’s workload. The working groups’ share is reviewing their migrated pages (R-23 one central conversion, R-26 owner review of migrated pages).
Lower contribution barrier: Any developer familiar with Markdown and GitHub can contribute documentation without learning a proprietary toolchain.
(L151)
Position. Contributing does not need a proprietary toolchain today. Pages
are Markdown with HTML and ERB tags (ERB is Ruby’s templating syntax,
<%= … %>; glossary) and can be edited on GitHub, as
any source file shows, for example
uaa-concepts.html.md.erb
(Docs WG lead, non-public pre-review). Bookbinder, the tool that
assembles the book, is open source: its repository’s
LICENSE is Apache-2.0, while its
gemspec declares MIT. The real costs
are elsewhere: see Keep and pain.
Community ownership: Documentation deployment is run transparently by the Docs WG without depending on CFF staff.
(L154; L54 also says “removing any dependency on CFF staff”)
Position. Nobody depends on Cloud Foundry Foundation (CFF) staff for the
docs work today: it is done in the working groups (Docs WG lead, non-public
pre-review). The Docs WG charter’s scope is to
“Merge and edit all doc changes”,
and the book’s
CODEOWNERS
names a working-group approvers’ team. What is outside the community’s control is the hosting (L24),
which is a separate point. These two sentences should be removed or
restated as a hosting benefit.
localhost:4567, and Bookbinder’s watch command runs
middleman server
to serve it. The gap is the setup it needs
(R-12 one-command local preview)._oss_scale_table, a table file
that the high-availability page includes
(sources). Every tool in the
tables round included it from a host page, Docusaurus through an MDX
import (Docusaurus conventions,
“Partials”). Partials picked by a
variable are not needed (R-05 partials and reuse).20a4122:
table survey, bosh.io); see Research areas.From the concept rounds: every concept in the
concepts list now has a round, and each
round’s conventions are under review. The headings round bears on
R-01 content and outline survive and R-16 old URLs keep
working; its conventions are under review
(headings results). The
notes round bears on R-07 notes and admonitions and R-24
markup cleanup before conversion
(notes results). The variables
and partials rounds bear on R-04 variables everywhere and
R-05 partials and reuse
(variables results,
partials results). The
build-time values round bears on R-25 build-time values are
expected differences
(build-time values results).
The cross-repository links round bears on R-08 cross-repository
links, R-15 URL identifies the source and R-16 old URLs
keep working
(cross-repository links results).
The code blocks round bears on R-06 typed code blocks and
R-24 markup cleanup before conversion: every tool meets R-06 once
blocks are written as its own code blocks with a type, bash for commands
and console for sessions
(code blocks results). The
reviews will sharpen the requirements from R-04 variables
everywhere to R-08 cross-repository links.