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).
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.
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.
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.
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 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.
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.
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.
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.
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.
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 © <%= 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.
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).