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
Content and document outline are preserved ideally. The words, code,
links, heading tree, and order of sections should survive conversion. A
conversion may restructure content when the source structure was chosen for
formatting reasons (for example, short phrases set as a list where sentences
would read better as paragraphs). Every such change is deliberate and
recorded as a deviation.
Everything else is a hint. Column widths, alignment, wrapping, and
similar presentation details express author intent, not exact values. Each
tool and template honors hints as well as it can. Hints are tool-neutral.
The first ones are drafted in Tables and
move to a shared hints.md once a second concept needs them.
Appearance is not compared. Fonts, colors, and heading styles belong to
the site template. A converted page can look different from the published
page and still be correct.
The source format is open. Markdown is one candidate, not a requirement.
HTML passthrough and tool extensions are first-class options. Formats are
judged by whether they meet the requirements of each user group.
Open source only. Every tool in the evaluation is open source.
Candidate tools
Tier
Tools
Work
Hands-on
Zensical, Docusaurus, Astro/Starlight, Antora
Each concept converted by hand, conventions recorded
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.