mkdocs2hextra

Overview ¶

Command mkdocs2hextra converts an MkDocs Material site to Hugo with this fleet's Hextra fork.

It exists because the fleet has EIGHTY-FIVE of them — 575 pages, measured — and the conversion is the same five mechanical steps every time, four of which are invisible when done wrong:

1 252 links to a .md file   Hugo serves /page/, not /page.md. Rewritten to
                            {{< relref >}}, which FAILS THE BUILD when the
                            target is missing instead of 404ing later.
  209 admonitions           !!! note "…" → Hextra's callout shortcode,
                            across nine kinds; the collapsible ??? form
                            becomes details.
   24 content tabs          === "label" → one tabs shortcode per run.
   84 attribute lists       {: .class } carries a stylesheet that does not
                            come with the pages; dropped and counted.
   82 sites on mike         each documented version had its own path, so
                            the Hugo build keeps one: params.docs.version
                            reaches --baseURL in CI.

⛔ IT PREVIEWS BY DEFAULT AND WRITES ONLY WITH --apply. A converter that writes on sight is one that cannot be read before it runs, and the diff of a migration is the only review it will ever get.

⛔ AND IT NEVER DELETES. mkdocs.yml, requirements.txt and the old workflow are LISTED for the person to remove in the same commit, because a tool that removes the old site and writes a broken new one leaves nothing to go back to. git is the undo, and a tool should not be the only thing standing between a repository and its history.

mkdocs2hextra ~/src/go-asmgen/docs              # say what it would do
mkdocs2hextra --apply ~/src/go-asmgen/docs      # write it
mkdocs2hextra --apply --version v0.3.1 ~/src/x  # a release, not main