Skip to content

Hugo and the Hextra fork, instead of MkDocs Material and mike - #11

Merged
tannevaled merged 1 commit into
mainfrom
hugo-and-the-hextra-fork
Oct 18, 2026
Merged

tannevaled merged 1 commit into
mainfrom
hugo-and-the-hextra-fork

Conversation

@tannevaled

Copy link
Copy Markdown
Contributor

One of the fleet's 85 MkDocs sites, moved to Hugo and the
Hextra fork pinned at v0.16.0.

Converted by mkdocs2hextra,
not by hand. Its own report:

note: built from a MODIFIED tree at b7753702cffe -- this reading is not reproducible from any commit.
go-webengine docs: 4 pages in the nav
  wrote .github/workflows/docs.yml                     5706 bytes
  wrote README.md                                      1237 bytes
  wrote content/en/_index.md                           6021 bytes
  wrote content/en/architecture.md                     4998 bytes
  wrote content/en/fidelity.md                         5334 bytes
  wrote content/en/roadmap.md                          4043 bytes
  wrote hugo.yaml                                      2625 bytes
carried over: 0 callouts, 0 details, 0 tab sets, 7 links, 0 attribute lists dropped, 0 snippets left, 0 mermaid

still there, and the old site builds from them — remove in the same commit:
  mkdocs.yml
  requirements.txt
  docs/ (5 entries — the pages are now under content/en/)

this site was versioned with mike: the Hugo build keeps a path per version (params.docs.version = "main")
the nav's order becomes Hugo's weight — nothing else in either system knows it
every link to a .md file becomes {{< relref >}}: Hugo serves /page/, not /page.md, so every one was broken by the move, and a relref fails the build when its target is missing
each documented version keeps a path of its own (/docs/<version>/, latest following the newest), which is what mike was doing
MkDocs Material + mike needed a Python toolchain, a requirements.txt and a pip install in CI to render a static site for a pure-Go organisation

⛔ It was built locally before this branch was pushed, with
--panicOnWarning: nothing is committed for a site that does not build.

⛔ The branch is cut from origin/main, not from the local one.

🤖 Generated with Claude Code

@tannevaled
tannevaled force-pushed the hugo-and-the-hextra-fork branch 2 times, most recently from 007f180 to 5839722 Compare October 18, 2026 19:28
12 of the 85 sites write their card grids as `<a href="page.md">` (md_in_html), which a Markdown-link rewrite cannot see. Hugo does not mind — an attribute is an attribute — so this reached CI, where the link checker found three dead links on go-aiquota/docs' front page.

Re-converted with the fixed mkdocs2hextra, and the local gate now reads the BUILT HTML for .md hrefs as well as building it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@tannevaled
tannevaled force-pushed the hugo-and-the-hextra-fork branch from 5839722 to e8fba65 Compare October 18, 2026 19:42
@tannevaled
tannevaled merged commit 1971663 into main Oct 18, 2026
2 checks passed
@tannevaled
tannevaled deleted the hugo-and-the-hextra-fork branch October 18, 2026 20:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant