cf-docs-rfc-proposal

Keep and pain

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

What works in today’s docs and must survive the move, and what causes problems. Each item names the requirements it leads to, from the requirement list. The RFC is cloudfoundry/community#1642, the draft request for comments that proposes the new docs stack; quotes from it link to their line, as in L20 (glossary).

How the docs are built today. The pages live in the 12 docs-* content repositories listed in the book’s config.yml as .html.md.erb files (examples): Markdown with HTML mixed in and ERB tags (Ruby’s templating syntax, <%= … %>; glossary). Bookbinder, a Ruby tool, collects the repositories listed in the book’s config.yml into one site (glossary). It hands them to Middleman (Bookbinder’s gemspec), a Ruby static site generator (a program that turns text files into a website; glossary), which renders the pages. The book’s layout, styles and settings live in docs-book-cloudfoundry, whose Gemfile pins bookbindery 9.12.1; the book’s container uses 10.1.18 (container Gemfile).

What to keep

A page’s URL tells you which file to edit

docs.cloudfoundry.org/adminguide/metadata.html is metadata.html.md.erb in the docs-cf-admin repository: the book’s config.yml maps the adminguide directory to that repository, and the file name follows the page name (source). The Docs WG lead asked in a comment on the RFC pull request that this mapping be kept.

Leads to: R-15 URL identifies the source.

HTML where Markdown falls short

Authors use Markdown where it is enough and HTML where it is not. The test pages are published pages with complex tables that the Docs WG lead chose for testing tools (list). One of them, metadata, shows both: a simple three-column reference table written as a Markdown pipe table (one row per line, | between cells), and two HTML tables with a spanning title row and bulleted lists in cells (source). Across the book’s repositories (those that feed docs.cloudfoundry.org), 123 of 195 tables are HTML (this evaluation’s table survey, 2026-10-09).

Leads to: R-10 simple text plus HTML where needed, R-02 rich tables.

Variables and partials

A variable is a named value defined once and inserted into pages when the site is built: <%= vars.platform_name %>, defined in the book’s template_variables.yml (272 variables). A partial is a file of content included in other pages: <%= partial 'oss_scale_table' %>. Four of the five test pages put variables inside table cells; one test page is a partial (test pages).

Leads to: R-04 variables everywhere, R-05 partials and reuse.

Local preview

The book’s README describes a local preview: “Bookbinder assembles the doc set from your local copies and skips any content repositories you do not have checked out. Point your browser at localhost:4567 to preview your changes. On save, your browser reloads with any additional changes.” A container setup for the same preview is in the book’s docker/ folder. The code agrees: Bookbinder’s watch command runs middleman server.

Leads to: R-12 one-command local preview. The RFC’s Problem list says the opposite (L20); see the requirements page.

The Docs WG publishes

The Docs WG lead and the approvers merge pull requests today; the book’s CODEOWNERS file names the approvers’ team. The book’s README still says “Only the CFF Docs WG lead can merge pull requests, build to staging, and publish the documentation.” The RFC keeps merging and publishing with the Docs WG (L54).

Leads to: R-14 Docs WG approves and publishes.

Redirects for moved pages

The book has a redirect file, redirects.rb, with 85 redirect rules (84 permanent, 1 temporary): one sends all http traffic to https, the rest cover pages that moved, including all of /bosh/ to bosh.io/docs.

Leads to: R-16 old URLs keep working. These redirects must be carried over, not only new ones for the migration.

What causes problems

Bookbinder is no longer maintained

The pre-review of the RFC (comments on an earlier draft, in a document that is not public; a pull request comment records it) agreed that unmaintained dependencies are the main reason to move. Bookbinder’s repository has its last commit on 2024-10-17 (checked 2026-10-10), and the book’s container runs Ruby 2.6.9, which reached its end of life on 2022-04-12.

Middleman itself still runs. A probe (a small test that answers one question; glossary) built all five test pages with Middleman 4.6.3 on Ruby 4.0.7 and no Bookbinder, using a short configuration file and a small layout; every table matched the published page cell for cell (Middleman probe). So the problem is Bookbinder and the old Ruby setup, not the page format.

Leads to: R-12 one-command local preview. Beyond that requirement, it is the reason to move at all.

The RFC states “Search is broken or disabled” (L21).

Leads to: R-18 full-text search.

The book’s own files do not provide search. None of its layouts mentions it, and its search.html.erb holds only a title and an escaped <%%= yield %>, which prints as text (both at commit 30dfa57).

Not yet written: what search does on docs.cloudfoundry.org today, and since when.

Markup that only browsers tolerate

Some HTML is malformed in ways browsers repair without a sign. A strict parse of the test pages’ tables found 5 of 12 not well-formed (well-formed: every tag closed and nested properly, every attribute value quoted; glossary): an unclosed <col>, a <td> never closed, class=“table” with typographic quotes, a row ending in </td> instead of </tr> (details). A survey of all 238 tables (the book’s 195, bosh.io’s 40 and 3 in tutorial repositories) found more (this evaluation’s table survey, 2026-10-09): 5 tables never close <thead>, 8 classes are in typographic quotes, and 1 class has a mismatched quote.

Strict tools fail on this markup (MDX stops the build) or change the text without an error (Markdoc). MDX is Markdown that can also hold JSX, the HTML-like syntax of the React library (glossary); Markdoc is Markdown with {% %} tags (glossary).

Leads to: R-24 markup cleanup before conversion.

Column widths written four ways

Four of the five test pages set column widths, each a different way: <col width>, <th width>, <td width> and <th style="width:…"> (sources). In troubleshooting_slow_requests the same table shape appears six times with widths on some rows and not others. The tables round (the first concept, converted by hand in four candidate tools) found that a column’s role (a short key, a value, or prose) gives a better result than the written numbers.

Leads to: R-03 column widths as hints, R-09 table styles by class.

HTML-valued and undefined variables

Some variables hold HTML: route_services is a whole <p class="note"> paragraph (template_variables.yml). Today it renders as markup; MDX, Markdoc and EJS (a JavaScript templating syntax close to ERB; glossary) escape it, so the reader would see the tags as text unless the conversion handles it.

Two variables the test pages use, metadata_ref and bosh_cli_link (three times), are defined nowhere in the book, so the published pages show empty text in their place and nobody is told (sources).

Leads to: R-04 variables everywhere.

The footer is written &copy; <%= Time.now.year %> Cloud Foundry Foundation in the book’s _book-footer.erb, so the year is the build date, whether or not any content changed. A comparison of converted and published pages has to allow for this. Whether the year should follow content changes instead is an open question.

Leads to: R-25 build-time values are expected differences.

Hosting outside the community’s GitHub organization

The RFC states: “The current hosting solution involves infrastructure managed outside the community GitHub organization, leading to cost, access, and governance concerns” (L24).

Leads to: R-14 Docs WG approves and publishes, R-27 a named owner for every task.

Not yet written: where the site is hosted today, who pays for it, and who controls the domain. The RFC asks the last one (L178).