cf-docs-rfc-proposal

Concepts

The migration is worked one documentation concept at a time. For each concept, real pages are converted by hand into each candidate tool, the conventions that work are recorded, and those conventions later drive the scan and convert commands of cf-docs-migrate, a migration tool still to be written.

Principles

Candidate tools

Tier Tools Work
Hands-on Zensical, Docusaurus, Astro/Starlight, Antora Each concept converted by hand, conventions recorded
Probe Eleventy (EJS variables), Sphinx/MyST (directive hints), Middleman without Bookbinder (minimal-change baseline) One page per probe
On paper Hugo, VitePress Capability check against requirements

Concepts

Concept Status Why it matters
Tables Done, with open items: results Complex HTML tables (widths, spans, lists and paragraphs in cells, variables in cells) are the main reason the content is not plain Markdown today
Copyright and build-time values Done, with open items: results The footer year and “Page last updated” are computed at build; comparisons must mask them, and converted pages need dates that survive conversion. The year follows content: the newest content year on the site.
Headings Done, with open items: results Simplest concept; establishes the outline check
Variables Done, with open items: results <%= vars.* %> from template_variables.yml; some values contain HTML or Markdown
Partials Done, with open items: results <%= partial '...' %>; some partial names are themselves stored in variables
Notes and admonitions Done, with open items: results <p class="note"> with note__title spans
Code blocks Done, with open items: results Shell, console, JSON, YAML; copy button. 592 of the book’s 1,777 code blocks are HTML <pre>, which no tool types or gives a copy button
Cross-repository links Done, with open items: results Links between content repositories must survive conversion