cf-docs-rfc-proposal

Requirements

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

What this is

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:

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.

Relation to RFC #1642

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”.

Parts

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

Requirements

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:

Content

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

Authoring

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

Publishing and governance

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

Site

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

Migration

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:

Where the RFC is wrong or incomplete

Extensions (L100, L104)

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.

Who does the conversion work (L160 vs L131)

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).

Positive bullets the Docs WG lead disputed (L151, L154)

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.

Also incomplete

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.