Status: draft, incomplete — covers what is known as of 2026-10-10.
Terms used in the requirements,
tooling and POC documents. Each of
those documents defines a term where it first uses it, so none of them needs
this page; this page is for going further. Each entry says what the term is,
where it matters in this repository, and where to learn more. Quotes from
RFC #1642 are from its text at commit c737539 and link to the line.
The markup language of web pages. The CF source pages are Markdown that switches to HTML wherever Markdown falls short, above all for tables: column widths, lists and paragraphs in cells, a title row spanning the columns. RFC #1642 asks for the “Ability to handle HTML, especially HTML tables with column-width specification supported” (RFC L42). Why tables come first and what the test pages’ HTML looks like: concepts/tables/README.md.
Learn more: HTML standard, MDN HTML reference.
A plain-text writing format: # for headings, - or * for lists,
backticks for code, and HTML allowed wherever Markdown has no syntax of its
own. It has many dialects (CommonMark, GFM, kramdown, Python-Markdown and
others) that agree on the basics and differ on tables, attributes and edge
cases. RFC #1642 says the docs “SHOULD be rewritten in plain Markdown”
(RFC L31); this repository treats Markdown as one candidate, not a
requirement (“The source format is open”, concepts/README.md).
Learn more: CommonMark (includes a short tutorial).
A precise specification of Markdown’s core syntax, with a test suite, written to end the disagreements between Markdown implementations. It has no tables; GFM adds them. MDX (Docusaurus), Markdoc (Starlight) and markdown-it (the Eleventy probe) all parse CommonMark: MDX parses with remark-parse, which parses according to CommonMark, and Markdoc (package.json) and Eleventy (package.json) use markdown-it, which follows the CommonMark spec (each project’s own description). Python-Markdown (Zensical) follows the older original Markdown rules (its documentation), which is one reason the same page can need different indentation per tool (tooling/formats.md).
Learn more: CommonMark.
GitHub Flavored Markdown: CommonMark plus pipe tables, strikethrough, task lists and automatic links. GitHub uses it to show Markdown files (the GFM specification, GitHub’s own description), including the pages of this repository read raw. Docusaurus’s native mode writes GFM pipe tables (sites/docusaurus/CONVENTIONS.md), and this repository’s Pages build reads its Markdown as GFM (_config.yml).
Learn more: GFM specification.
Markdown’s table syntax from GFM: one line per row, cells separated by
|, and a line of dashes under the header row. A cell holds one line of
inline text, so a list or a second paragraph in a cell needs inline HTML,
and there are no widths, row headers or spanning cells, only left, center or
right alignment per column. Docusaurus native, Zensical native and
native-plain, and Starlight native-plain use pipe tables; the round found
that “List-table syntaxes carry most hints; pipe tables carry few”
(concepts/tables/README.md).
Learn more: GFM specification, tables.
A Markdown converter written in Ruby and the default in Jekyll (configuration.rb). It has its own syntax for attributes and can also read GFM. Only this repository’s own GitHub Pages build uses it (_config.yml); none of the candidate tools does, and the published CF book uses a different Ruby Markdown engine, Redcarpet (probes/middleman/README.md; Bookbinder gemspec).
Learn more: kramdown.
A Markdown converter written in Python, extended through plug-ins such as
tables, attribute lists and the pymdown-extensions collection. It follows the
original Markdown rules rather than CommonMark, so nested lists need
four-space indents (the default
tab_length is 4;
its documentation).
Zensical
(pyproject.toml)
and MkDocs
(pyproject.toml)
read pages through it; it passes HTML
blocks through as written, which is why all five test pages build unchanged
in Zensical, and Zensical’s extension mode is a Python-Markdown block
(sites/zensical/CONVENTIONS.md).
Learn more: Python-Markdown.
Markdown with JSX: a page can import components and data and use them as
HTML-like tags, and {…} holds a JavaScript expression. MDX compiles the
whole page, its HTML included, as JSX, so markup that browsers tolerate stops
the build and literal braces in prose must be escaped; all five test pages
failed as written
(results.md).
Docusaurus 3 uses MDX 3
(mdx-loader package.json),
which the RFC names as the replacement for ERB
(RFC L31, L39). RFC §5 says “The PoC MUST validate that the
most complex existing pages (HTML tables, CSS layouts) can be represented
with MDX alone” (RFC L104).
Learn more: MDX.
An HTML-like syntax inside JavaScript, used by React to describe what a
component renders. It is stricter than HTML: every element must be closed
(<br />), style takes an object (style={{width: '20%'}}), and braces
start an expression. MDX reads a page’s HTML as JSX, which is where most of
Docusaurus’s passthrough cleanup comes from
(sites/docusaurus/CONVENTIONS.md).
Learn more: JSX in MDX; Writing markup with JSX (React).
Markdown with {% %} tags, made by Stripe for its own documentation
(README,
the project’s own description). Tags
such as {% table %} and {% partial %} add structure, and {% $name %}
prints a variable. In this evaluation Starlight reads Markdoc pages (.mdoc)
with HTML allowed. Markdoc reads the text inside HTML as Markdown, which
changed content without an error in passthrough (a lone - became a list,
spaces next to inline tags disappeared), while its own table tag carries
widths and lists in cells
(results.md).
Learn more: Markdoc.
A plain-text markup language with a larger built-in vocabulary than
Markdown: tables with widths and row headers, admonitions, includes and
attributes (variables) are part of the language. Asciidoctor is the usual
processor; Antora runs it
(asciidoc-loader package.json).
Antora reads only AsciiDoc, so every test page was rewritten from
Markdown in every mode, and that rewrite failed silently in four ways
(results.md); its tables are written
[%header,cols=…] between |=== lines
(sites/antora/CONVENTIONS.md).
Learn more: AsciiDoc, Asciidoctor.
Markedly Structured Text: a Markdown dialect that adds the directives and
roles of reStructuredText, Sphinx’s original format. A directive is a fenced
block with a name and options, such as {list-table}. The Sphinx probe
writes the scale table as a MyST list table and takes the CF variables in as
substitutions
(probes/sphinx-myst/README.md).
Learn more: MyST, MyST parser for Sphinx.
A table written as a nested list: each row is a list item and each cell an
item inside it, so a cell can hold lists and paragraphs. It comes from the
list-table directive of reStructuredText, which MyST also has; its options
name the widths, header rows and row-header columns (widths,
header-rows, stub-columns). The extension modes for Docusaurus and
Zensical add a list table with the same option names, and Starlight’s
extension puts them on Markdoc’s table tag
(sites/docusaurus/CONVENTIONS.md,
sites/zensical/CONVENTIONS.md).
Learn more: MyST parser, tables,
reStructuredText list-table.
Embedded Ruby: Ruby code inside a text file between <% and %>, where
<%= prints the result. The CF source pages are .html.md.erb files: ERB
runs first, then Markdown. They use it for variables (<%= vars.name %>)
and partials (<%= partial 'name' %>), and in Middleman <%= does not
escape HTML, so an HTML-valued variable renders as markup
(probes/middleman/README.md).
RFC #1642’s first problem is that “Documentation is written and maintained
using ERB/Ruby templates and a custom HTML pipeline” (RFC L19).
Learn more: ERB.
Embedded JavaScript templates: the same <% %> tags as ERB, with JavaScript
inside. The difference that matters here is escaping: EJS’s <%= escapes
HTML and <%- does not, where the CF pages’ <%= in Middleman does not
escape. The Eleventy probe built uaa-concepts and the scale table with
their ERB variable tags read as EJS; HTML-valued variables, helpers and includes need <%-
(probes/eleventy/README.md).
Learn more: EJS.
A template language from Shopify, with {{ name }} and {% tag %}
syntax, used by Jekyll
(jekyll.gemspec)
and other tools. No candidate tool in this
round uses it. This repository’s Pages build turns Liquid off, because code
samples in these documents use Markdoc and other syntax that looks like
Liquid and would otherwise be run (_config.yml).
Learn more: Liquid.
A block at the very top of a page, between two --- lines, that holds the
page’s settings in YAML, such as its title. The CF source pages have one,
with title and owner
(source/credential-types.html.md.erb).
Most candidate tools read front matter, each with its own keys; AsciiDoc
(Antora) uses header attributes instead. Docusaurus takes a page’s
description from the first paragraph unless the front matter sets
description:, which put raw variable expressions into two descriptions
(results.md).
Learn more: Front matter in Jekyll.
A program that turns source files (Markdown, templates, a theme) into a folder of finished HTML pages before anyone visits the site, so the server only hands out files. RFC #1642 proposes that the docs be “managed via a modern static site generator” (RFC L31) and hosted on GitHub Pages, which is a static site hosting service (GitHub’s description). Every tool in this evaluation is one, today’s Bookbinder and Middleman included; the tiers are in concepts/README.md.
Learn more: MDN glossary: SSG.
The Ruby tool that builds today’s docs.cloudfoundry.org: it collects the
docs-* content repositories listed in docs-book-cloudfoundry’s
config.yml
into one “book” and builds it with Middleman (a runtime dependency in its
gemspec).
Each repository maps to a fixed URL directory, so a page’s URL tells you
which repository and file to edit (README.md), and
it already offers a local preview
(book README;
the watch command runs
middleman server).
The Middleman probe asks what is left when Bookbinder is removed: a short
configuration and a layout
(probes/middleman/README.md).
Learn more: Bookbinder, docs-book-cloudfoundry.
A Ruby static site generator; Bookbinder uses it to render the book’s ERB, Markdown and HTML into pages (Bookbinder gemspec). The Middleman probe built all five test pages unchanged with Middleman 4.6.3 on Ruby 4.0.7 and no Bookbinder, and every table matched the published page cell for cell. It is the minimal-change baseline: Bookbinder goes, the source format stays (probes/middleman/README.md, requirements/keep-and-pain.md).
Learn more: Middleman.
A documentation site generator from Meta (LICENSE: “Copyright (c) Facebook, Inc. and its affiliates”), built on React; pages are Markdown or MDX (package.json). RFC #1642 says “The recommended engine is the current major version of Docusaurus” (RFC L31). A hands-on tool here (3.10.2): no test page built with its HTML unchanged, every table rendered correctly after cleanup, and its pipe tables carry no width hints (results.md, sites/docusaurus/CONVENTIONS.md).
Learn more: Docusaurus.
A static site generator from the creators of Material for MkDocs
(README,
the project’s own description); it reads Markdown through Python-Markdown
(pyproject.toml)
and can build existing MkDocs projects: it reads mkdocs.yml
(config.py). A hands-on tool here (0.0.69): all five test pages built with their
HTML unchanged, and the variables kept their ERB form through its built-in
macros support
(results.md,
sites/zensical/CONVENTIONS.md).
Learn more: Zensical.
Material for MkDocs: a theme and set of plugins for MkDocs
(pyproject.toml),
a Python static site generator that reads Markdown through Python-Markdown
(pyproject.toml).
RFC #1642 says “Other frameworks such as Hugo or MkDocs MAY be evaluated and
proposed as alternatives during the PoC phase” (RFC L31). It is not a
hands-on tool in this round, but bosh.io’s documentation (docs-bosh, owned
by the FI WG:
charter)
is built with it
(mkdocs.yml,
ci/tasks/build.yml),
which matters for how bosh.io relates to the new
site (requirements/audiences.md,
tooling/tools.md).
Learn more: MkDocs, Material for MkDocs.
A documentation framework for Astro, a JavaScript site builder
(package.json).
Starlight reads Markdown and MDX by default
(package.json);
here it ran with Astro’s Markdoc integration
(@astrojs/markdoc),
so the pages are Markdoc with HTML allowed (Starlight 0.42.6,
Astro 7.3.8). Four of five pages parsed with their HTML unchanged, but
Markdoc changed text inside HTML without an error, and Markdoc’s own table
tag carries widths and lists in cells with no custom code
(results.md,
sites/starlight/CONVENTIONS.md).
A documentation site generator for AsciiDoc that builds one site from content kept in many git repositories, organized as versioned components (aggregate-content.js; README). A hands-on tool here (3.2.1): every page had to be rewritten as AsciiDoc, while the HTML tables built unchanged inside passthrough blocks. AsciiDoc’s own tables carry most hints, and the extension needs no code, only roles and a stylesheet (results.md, sites/antora/CONVENTIONS.md).
Learn more: Antora.
A Python documentation generator that reads reStructuredText and, with the myst-parser extension, MyST Markdown (myst-parser pyproject.toml). It ran as a probe (Sphinx 9.1.0, myst-parser 5.1.0) to see whether list-table options carry the table hints: the header row, row headers and widths yes, and the column roles and capped no-wrap through classes and CSS, with no code (probes/sphinx-myst/README.md).
Learn more: Sphinx.
A JavaScript static site generator (also written 11ty) that accepts many
template languages; since version 3, EJS is a plugin: ejs is a dependency
of Eleventy
2.0.1
but not of
3.0.0,
and it comes from
@11ty/eleventy-plugin-ejs.
It ran as a probe
(3.1.6): with the CF pages’ <%= vars.* %> tags left as they are and read as
EJS, the uaa-concepts tables and the scale table came out byte for byte
as written
(probes/eleventy/README.md).
Learn more: Eleventy.
A static site generator written in Go (go.mod), with templates in Go’s template syntax (tpl/internal/go_templates). RFC #1642 names it, with MkDocs, as an alternative that “MAY be evaluated” (RFC L31). In this evaluation it is an on-paper tool, not yet assessed (concepts/README.md, tooling/tools.md).
Learn more: Hugo.
A documentation site generator built on Vite and Vue; pages are Markdown, read by markdown-it, with Vue components allowed (package.json, markdown-it). In this evaluation it is an on-paper tool, not yet assessed (concepts/README.md, tooling/tools.md).
Learn more: VitePress.
A Ruby static site generator and the engine behind GitHub Pages’ built-in builds (GitHub’s documentation); it reads Markdown with kramdown and templates with Liquid (jekyll.gemspec). It is not a candidate tool. This repository’s own Pages site is built with Jekyll 4 by a workflow (.github/workflows/pages.yml), with Liquid turned off and the tool folders left out (_config.yml).
Learn more: Jekyll.
A tool, built on Middleman (the copy in UAA’s repository pins it in its
Gemfile),
that turns Markdown into a single-page API reference with navigation,
explanations and code samples side by side. The UAA API documentation is
built with Slate from snippets that Spring REST Docs generates, outside the
Bookbinder book. UAA’s build runs the *Docs tests to write the snippets,
then middleman build in its Slate copy
(uaa/build.gradle.kts). RFC #1642’s summary covers
“the Cloud Foundry documentation (CF, UAA API)” (RFC L13). Who
maintains these docs and what they need is in
requirements/audiences.md.
Learn more: Slate.
A Spring project that documents a REST API from its tests: each test that calls the API writes request and response snippets, which the documentation pages include. The CredHub API docs use it (backends/credhub/build.gradle), and it feeds the UAA API’s Slate pages (uaa/build.gradle.kts), so these docs are partly generated from code rather than written by hand. RFC #1642 asks “Who can we involve to vet this proposal for the UAA API docs and the CredHub API docs?” (RFC L177); see requirements/audiences.md.
Learn more: Spring REST Docs.
One kind of documentation content, such as tables, variables, partials, notes or code blocks, taken as the unit of work. For each concept, real pages are converted by hand into each candidate tool and the conventions that work are recorded; those conventions later drive the conversion tool. Tables is the first concept and the only one done so far (concepts/README.md).
Learn more: concepts/README.md.
The real CF pages used for the tables concept: five pages the Docs WG lead
picked because their tables are hard to express outside HTML, plus a sixth,
uaa-performance, added later as the example of a second table style, and a
seventh, _oss_roles_table, added on 2026-10-12 as a real wide table. They
are copied verbatim with their commits and licenses
(source/SOURCES.md).
Learn more: concepts/tables/README.md.
One file per test page that says, for each table, what the source asks for in tool-neutral hints, what markup cleanup it needs, which deviations from the published page are deliberate, and which spot checks every converted version must pass. It is written before any tool is tried, so every tool is judged against the same intent. Example: intent/credential-types.md.
Learn more: concepts/tables/README.md.
What a table asks for, written once and independent of any tool: a column’s role, a width, “don’t wrap”, row headers, a title, a style. A hint expresses the author’s intent, not an exact value, and each tool and template honors it as well as it can (“Everything else is a hint”, concepts/README.md). The requirement is R-03 column widths as hints (requirements/README.md).
Learn more: Hints after the round.
A hint that says what a column holds: key (a short label or identifier,
often code), value (a short value) or prose (sentences). The role sets a
column’s default width, wrapping and alignment, so most tables need no
explicit widths; a key column avoids wrapping by default. No tool’s table
syntax carries roles, so they travel as classes with CSS, or through a small
extension (results.md).
Learn more: Hints after the round.
A hint (wrap: avoid) that keeps a column’s text on one line; key
columns have it by default. It wins over a width, so the column grows, but
only up to a cap the template sets (--table-nowrap-max, 16em by default),
past which the text wraps between words: the “capped no-wrap”. Like the
column roles, it needs CSS in every tool
(results.md).
Learn more: Template conventions.
One of the ways each test page is converted into a hands-on tool:
passthrough, extension, native and native-plain, plus raw passthrough as a
check. Comparing modes shows what each tool costs at each level of change to
the source. Each site’s CONVENTIONS.md has a section per mode, for example
sites/zensical/CONVENTIONS.md.
Learn more: Method.
The mode that keeps each table’s HTML as written, translating only variables
and partials to the tool’s syntax, plus the cleanup the intent files list and
whatever the tool forces. It answers how much must change if authors keep
writing HTML tables (R-10 simple text plus HTML where needed,
requirements/README.md). The forced changes are in
each site’s CONVENTIONS.md; Antora keeps the HTML inside an AsciiDoc
passthrough block (++++), which it does not parse
(sites/antora/CONVENTIONS.md).
Learn more: Method.
Passthrough with no cleanup: the source HTML exactly as published, with only the variables and the partial line translated. It shows which tools take today’s markup, browser-tolerated defects included: Zensical, Antora and the Middleman probe built all five pages, MDX failed on all five, and Markdoc parsed four while changing text inside HTML. Each tool’s section in results.md ends with its raw results.
Learn more: Raw passthrough errors in Docusaurus.
A tool’s own plug-in point, used to carry the hints its table syntax cannot. Docusaurus uses a remark plugin, Zensical a Python-Markdown block, and Starlight attributes on Markdoc’s table tag (85 lines). Antora and the Sphinx probe need only classes and a stylesheet, no code. RFC #1642 says “Working Groups MUST NOT need custom extensions, plugins, or JavaScript code to author documentation” (RFC L100). Extension mode shows which gaps such code closes. Who may write extensions is a separate question (R-13 no per-WG extensions, requirements/README.md).
Learn more: results.md, remark.
The mode that writes each table in the tool’s own table syntax, with whatever
hint mechanism that syntax offers: pipe tables in Docusaurus and Zensical
(Zensical adds widths on header cells), Markdoc’s {% table %} tag in
Starlight, AsciiDoc tables in Antora. It shows how far an author gets with
neither HTML nor an extension. Native tables get the standard table style in
every tool, as decided
(results.md).
Learn more: Method.
Native mode with no width or alignment specs at all: pipe tables in
Zensical and Starlight, AsciiDoc tables without cols in Antora
(Docusaurus’s native mode is already plain). It shows what a table looks like
when the author writes only the content.
Learn more: Native with and without widths.
A specific, checkable statement about a converted page, such as “7 body
rows, each with 2 cells” for credential-types. Each intent file lists them
per table, and make check in each site runs them against the built pages
with checks/spot-checks.sh. Next to
them, the tables round compared each page’s text word by word with the
published page (checks/text-diff.py),
and the headings round checked each page’s headings and anchors
(checks/outline.py). A check of text
and headings for every migrated page belongs to
cf-docs-migrate (R-01 content and outline
survive, requirements/README.md).
Learn more: intent/credential-types.md.
The site-wide layout and look that every page is rendered into: header, navigation, footer, and how elements such as tables appear. Here it means the CF site’s chosen look, as opposed to a tool’s default theme, and not a templating language such as ERB. “Template conventions” are source markup that conversions drop because the template does it anyway, such as bold header cells; appearance belongs to the template and is not compared (concepts/README.md).
Learn more: Template conventions.
The package that gives a tool’s site its default look: layouts, CSS, sometimes scripts. This round used each tool’s default theme, so that hints must work under any theme. The themes disagree on which tables they style: Docusaurus and Starlight every table, Zensical only tables without a class, Antora only its own AsciiDoc tables, and the Antora and Sphinx themes hyphenate words in cells (results.md).
Learn more: results.md.
A class name on a table that names its look: class="table" for the
standard style, table-media for the image-grid example. Every HTML table
names its style with a class and each site’s CSS gives the class its look; a
pipe table cannot carry a class, so it gets the standard style (R-09 table
styles by class, requirements/README.md). Which
further styles to support is open
(concepts/tables/README.md); how
one is added is under “Adding a style” in each site’s CONVENTIONS.md.
Learn more: Template conventions.
A small experiment that answers a single question about a tool, short of a full hands-on round. There are three: Eleventy (do ERB variable tags work as EJS?), Sphinx with MyST (can list-table options carry the hints?) and Middleman without Bookbinder (what is the smallest change that removes Bookbinder?). Questions and answers are in results.md; the tiers in concepts/README.md.
Learn more: Probes.
A fragment of a page kept in its own file and included in other pages, so
shared content is written once. The CF pages include one with
<%= partial 'name' %>, and some partial names are themselves stored in
variables (scale_table: "oss_scale_table" in the book’s
template_variables.yml). RFC #1642 asks “Are partials
supported by Docusaurus? If not, the migration will have to integrate them
into their calling topics.” (RFC L179) In this round every tool
included the _oss_scale_table partial, Docusaurus as an imported MDX
component
(sites/docusaurus/CONVENTIONS.md;
R-05 partials and reuse). The partials round
found that no page at the surveyed commits picks its partial through a
variable, and converted six pages’ partials in all four hands-on tools
(partials results).
Learn more: Importing Markdown in Docusaurus.
A named value defined once and inserted into many pages, such as the
product name. The CF book defines them in template_variables.yml, pages
insert them with <%= vars.name %>, some values hold HTML (a note), and two
that the test pages use are not defined anywhere, so they render empty
(source/template_variables.yml).
RFC #1642 asks for the “Ability to handle variables in a way that’s easy and
transparent for contributers” (RFC L43); each tool’s syntax and how it
handles HTML values are in
results.md (R-04 variables
everywhere). The variables round counted 1,503 uses of 180 names, 28 of
them defined nowhere, and converted five pages’ variables in all four
hands-on tools (variables results).
Learn more: concepts/README.md.
A highlighted block that sets a note, tip or warning apart from the text
around it. The CF pages write notes as HTML, <p class="note"> with a
note__title span, and 12 variables hold such a note, 7 of them used by
pages (note survey).
Most candidate tools have admonition syntax of their own, such as :::note
in Docusaurus. RFC #1642 says customization “is handled by MDX 3 features of
the current Docusaurus version, such as admonitions” (RFC L100). The notes round converted
four pages’ notes into each tool’s admonition in all four hands-on tools,
checked with a notes check; its conventions are under review
(notes results;
R-07 notes and admonitions).
Learn more: Admonitions in Docusaurus.
HTML in which every element is closed and correctly nested and every
attribute value is properly quoted. Browsers repair markup that is not, and
say nothing; strict readers do not: MDX stops, and Markdoc changes content. A
strict parse found 5 of 12 tables, on 4 of 5 test pages, not well-formed: an
unclosed <col>, unclosed <td> cells, curly quotes around a class, a row
ended with </td>
(concepts/tables/README.md).
Cleaning this up before conversion is R-24 markup cleanup before conversion
(requirements/README.md).
Learn more: HTML standard.
Text shown as written, in a fixed-width font: commands, output,
configuration. Markdown writes it as a fence, three backticks and an info
string naming its type (```console); the book also writes 592 as
HTML <pre> blocks
(code blocks survey). A console
block holds commands with $ prompts and their output; a bash block
holds commands only. Why HTML <pre> blocks do not survive conversion:
code blocks results
(R-06 typed code blocks).
Learn more: Fenced code blocks in the CommonMark spec.
A value on a published page that the build computes instead of reading
it from the page’s source. The book has two: the footer’s copyright year,
<%= Time.now.year %>, and the “Page last updated” date, taken from Git
(build-time values survey).
A comparison of converted and published pages treats them as expected
differences (R-25 build-time values are
expected differences).
Learn more: concepts/build-time-values/README.md.
A link whose URL starts with /, such as /devguide/deploy-apps/routes-domains.html,
resolved from the site’s root rather than from the linking page’s folder.
A page-relative link, such as ../routes-domains.html, depends on where
the linking page sits, so in a variable or a partial it works at one folder
depth only
(cross-repository links results;
R-08 cross-repository links).
Learn more: URL standard, path-absolute URLs.
A folder or repository a tool reads pages from: a Docusaurus docs plugin instance, a Zensical docs folder, a Starlight content collection, or an Antora content source. Whether each content repository stays its own content source or moves into one repository changes edit links and how a tool takes in the other repositories, not the published URLs (cross-repository links results).
Learn more: Antora content sources.
The date a page’s content last changed: the author date of the newest
commit to the page that is not listed as a non-content commit. The list
uses the format of Git’s .git-blame-ignore-revs file, which git blame
and GitHub’s blame view
also read. The build-time values round proposes it
so that a conversion, which touches every page, does not reset every
page’s date
(build-time values results).
Learn more: git blame --ignore-revs-file.
The Cloud Foundry Documentation Working Group. Its charter’s mission is “To document the Cloud Foundry user experience” (charter L5), and its scope starts with “Merge and edit all doc changes” (L17). RFC #1642 keeps publishing with it: “Only Docs WG approvers can merge into the central repository and trigger deployments.” (RFC L54) The requirements in this repository are a draft Docs WG position (R-14 Docs WG approves and publishes, requirements/README.md).
Learn more: Docs WG charter.
The Foundational Infrastructure Working Group, whose scope covers BOSH, UAA
and CredHub and includes “Operate https://bosh.io”
(charter L15–L18).
It owns docs-bosh
(L352),
the bosh.io documentation, which is built with MkDocs Material outside the
Bookbinder book
(mkdocs.yml). How bosh.io’s docs relate to the new site is covered in
requirements/audiences.md.
Learn more: FI WG charter.
Request for Comments: in the Cloud Foundry community, a written proposal for
a change that affects the project, discussed in public as a pull request
against cloudfoundry/community and kept under toc/rfc. RFC #1642,
“Cloud Foundry Documentation Modernization” (RFC L3), is a draft that proposes moving
the CF docs to Markdown on a modern static site generator hosted on GitHub
Pages. These documents quote it by line at commit c737539, because a draft
changes; where they disagree, they say so next to the quote
(requirements/README.md).
Learn more: CF RFC process, RFC #1642.
The capitalized words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY, read with the meanings RFC 2119 gives them: MUST is an absolute requirement, SHOULD a recommendation that may be set aside for a good reason, MAY truly optional. RFC #1642 uses them throughout, for example “Key capabilities the chosen framework MUST provide” (RFC L33) and “Working Groups MUST NOT need custom extensions” (RFC L100). A requirement’s strength is in these words (requirements/README.md).
Learn more: RFC 2119.
Proof of concept: a small working build that shows whether an approach
works before anyone commits to it. In RFC #1642 the PoC is Phase 2: “A PoC
SHOULD be established in a new repository (e.g., cloudfoundry/docs-next)”
to stand up the chosen tool with a representative subset of the docs
(RFC L119–L127). The poc/ documents in this
repository compare the hand conversions of the test pages across tools:
evidence gathered ahead of that Phase 2, not the Phase 2 PoC itself
(tooling/poc-scope.md).
Learn more: RFC #1642.
A file in a GitHub repository that maps paths to the people or teams who own
them; GitHub then asks those owners to review every pull request that
touches their paths. RFC #1642: “The docs repository contains a CODEOWNERS
file that assigns each documentation area to the GitHub team of the
responsible Working Group” (RFC L74). Today’s source pages already
name an owner in their front matter (owner: CredHub;
source/credential-types.html.md.erb) (R-17 an owner for
every area,
requirements/README.md).
Learn more: About code owners.
GitHub’s hosting for static sites, built from a repository by a GitHub
Actions workflow or by GitHub’s own Jekyll build
(publishing sources). RFC #1642: “The
documentation site MUST be deployed to GitHub Pages under the cloudfoundry
GitHub organization” (RFC L50). This repository is published there
too (.github/workflows/pages.yml). Whether
the open-source-only principle covers services such as Pages is an open
question
(concepts/tables/README.md).
Learn more: GitHub Pages.
A hosted search service from Algolia, offered free to public technical documentation and technical blogs (who can apply): the Algolia Crawler extracts the site into an Algolia index, and the DocSearch packages query that index (what is DocSearch; both Algolia’s own description). The search client is open source (MIT) but needs an Algolia application ID and API key (DocSearch.tsx). RFC #1642 names it as an example of “Built-in full-text search” (RFC L36) and asks whether it “is the preferred search backend, or should a self-hosted option (e.g., Pagefind, lunr.js) be used?” (RFC L170). Pagefind runs over the built site and writes its search bundle into it (options.rs), so it needs no service. Because the index is hosted by Algolia, the choice touches the open question on open source (concepts/tables/README.md; R-18 full-text search, R-19 open source only).
Learn more: Algolia DocSearch, Pagefind.
A proposed convention: a Markdown file at a site’s root, /llms.txt, that
lists and summarizes the site’s main pages so that tools built on large
language models can find them. RFC #1642 lists “optionally an LLM-friendly
/llms.txt index” among the capabilities the framework must provide
(RFC L41) and asks whether one should be published (RFC L173).
Related: R-20 search-engine and AI-friendly output
(requirements/README.md).
Learn more: llms.txt.
The planned migration tool, not yet written. Its scan command would find
each concept’s patterns in the source and its convert command would apply
the conventions recorded in each site’s CONVENTIONS.md. It would also run
the automated content and outline check against the published pages,
treating build-time values such as the copyright year as expected
differences (concepts/tables/README.md).
The migration steps it serves are in
requirements/migration.md.
Learn more: concepts/README.md.