Status: draft Docs WG position, incomplete — covers what is known as of 2026-10-10.
The steps that take today’s docs to the new site, and what each step must achieve. This page says what each step does and which requirements it serves (requirement list). How a step is done in a given tool, and what that costs, is in Tooling. 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 L112 (glossary).
Today. The 12 docs-* content repositories listed in the book’s
config.yml hold the pages as .html.md.erb files
(examples): Markdown with HTML mixed in and ERB tags (Ruby’s
templating syntax, <%= … %>; glossary). Bookbinder, a
Ruby tool (glossary), collects the repositories
listed in the book’s config.yml and builds one site. Each repository maps
to one URL directory (the directory: of its section). Pages share
variables (named values defined once in
template_variables.yml and
inserted at build time) and partials (files of content included in other
pages). The book also holds the
layout,
the footer and
85 redirect rules (redirects.rb).
The new shape, as far as it is known.
CODEOWNERS file (a GitHub file naming who must review changes to which
paths) assigns each directory to its working group (R-17 an owner for
every area).List every repository, page, partial, variable and redirect that feeds the site, with the working group that owns each area. The RFC makes this the first phase (L112, L114). The inventory also records where each page’s URL comes from, so R-15 URL identifies the source and R-16 old URLs keep working can be checked later.
Serves: R-17 an owner for every area, R-15 URL identifies the source, R-16 old URLs keep working.
Done so far: a survey of every table in the docs and tutorial repositories
(238 tables), used to pick table styles (this evaluation’s
table survey, 2026-10-09).
The repository half of the inventory has a start: the book’s
config.yml
lists 12 sections, and the survey recorded the 21 repositories it read,
each with the commit it read
(shas.txt).
Not yet written: the rest of the inventory (pages, partials, variables, redirects and owners), and whether bosh.io and the UAA and CredHub API references are in it (research areas).
Fix the HTML that browsers accept but strict parsers reject: unclosed elements, typographic quotes around attribute values, rows that end with the wrong tag. Strict tools either stop the build or change the text without an error (details). Each fix is recorded, so the owner review in step 5 can see it.
Serves: R-24 markup cleanup before conversion.
Not yet written: whether fixes go to today’s repositories first (which also fixes the published site) or are made only during conversion.
A concept is one documentation feature: tables, headings, variables,
partials, notes, code blocks, cross-repository links
(concepts). Each concept is first converted by hand
in the candidate tools, and the conventions that work are recorded. Those
conventions become the rules of cf-docs-migrate, a migration tool still to
be written:
scan finds every instance of each concept across the content;convert applies the recorded rules to every page.One central team runs the conversion the same way for every repository (L131). Where the source structure was chosen only for formatting, a conversion may restructure it, and records the change as a deviation.
Serves: R-23 one central conversion, R-01 content and outline survive, R-04 variables everywhere, R-05 partials and reuse, R-07 notes and admonitions, R-08 cross-repository links.
Done so far: tables, for the test pages (published pages with complex tables that the Docs WG lead chose for testing tools; tables concept).
Compare each converted page with the published page: its text, headings, lists, tables and links. Differences that come from build time, such as the copyright year in the footer and “Page last updated”, are expected and not reported. Recorded deviations from step 3 are listed apart.
Serves: R-01 content and outline survive, R-25 build-time values are expected differences.
Done so far: per-page spot checks (checks every converted page must pass, listed for each test page) and a word-by-word text comparison, used in the tables round (checks). The headings round added an outline check: it compares each converted page’s headings, in order with their levels, with the published page and confirms the anchors to keep (outline.py). The notes round added a notes check: it compares each note’s kind, title, words, contents and place (notes.py).
The owning working group reviews each migrated section, with the report from step 4 and the list of deviations and cleanup fixes.
Serves: R-26 owner review of migrated pages.
Not yet written: what the owner signs off, and what happens when an owner does not respond.
Every published URL keeps working: today’s redirect rules are carried over, and every page whose address changes gets a new one. Heading anchors keep their ids where the conversion can keep them.
Serves: R-16 old URLs keep working (L46, L61, L137).
The new site goes live at docs.cloudfoundry.org; the old build system is
archived, not deleted; the old hosting is shut down after a stabilization
window, which the RFC suggests is 90 days (L135–L138). Current
maintainers have had time to learn the new toolchain before this step.
Serves: R-28 onboarding before cutover, R-14 Docs WG approves and publishes, R-16 old URLs keep working.
Not yet written: the timeline, which the RFC requires to be “published and agreed upon by all affected Working Groups” (L131); the order in which repositories move; and how edits made to today’s repositories during the conversion reach the new site (a freeze, or converting again).