chore(docs): migrate documentation site from VitePress to Hugo

[charles-fineman]

Outcome

The Grizzle documentation site builds and deploys with Hugo as its static-site generator, using a pinned, reproducible toolchain that does not require Node.js, npm, or VitePress. Existing documentation remains discoverable and usable at stable public URLs before the v1.0 release.

Context

Grizzle is a Go project, while the current documentation pipeline adds a separate Node.js/npm/VitePress toolchain. The site primarily uses VitePress's default documentation features—navigation, sidebar, local search, syntax highlighting, callout containers, edit links, and GitHub Pages deployment—rather than custom Vue components.

Moving to Hugo aligns documentation builds with the project's primary ecosystem and reduces cross-language build and dependency maintenance. This is an infrastructure migration, not a documentation redesign. A working production-build baseline must be retained so the migration does not hide pre-existing content, link, or deployment defects.

In scope

• Pin a supported Hugo version and document the upgrade policy.
• Choose and document a maintainable Hugo theme/layout strategy; avoid introducing a Node.js/npm build requirement through the theme or asset pipeline.
• Add Hugo configuration for local development and deployment under the GitHub Pages /grizzle/ base path.
• Convert VitePress-specific configuration, home-page frontmatter, Markdown callout containers, and other site-specific syntax to Hugo-compatible equivalents.
• Preserve the current guide, advanced, migration kit, reference, specification, and project-planning content hierarchy.
• Preserve existing public documentation URLs where practical and add redirects or aliases for unavoidable route changes.
• Reproduce the current user-facing essentials:
  • primary navigation and section sidebar
  • syntax highlighting
  • warning, tip, and information callouts
  • local documentation search
  • GitHub and “Edit this page” links
  • license/copyright footer
• Update the GitHub Pages workflow to install the pinned Hugo version, build the site, validate generated links, and publish the generated artifact.
• Remove VitePress configuration and Node/npm documentation dependencies after Hugo reaches feature and deployment parity.
• Update contributor documentation with the canonical local build, preview, link-check, and upgrade commands.

Out of scope

• Rewriting or broadly reorganizing documentation content.
• Redesigning Grizzle's visual identity or building a custom web application.
• Replacing pkg.go.dev or deciding a new Go API-reference strategy.
• Changing public documentation URLs without compatibility aliases or redirects.
• Authoring v1.0 release notes or CLI cutover guidance owned by other issues.
• Committing generated site output.

Acceptance criteria

• A clean checkout can build the complete documentation site with the documented pinned Hugo toolchain and without Node.js or npm.
• The GitHub Pages workflow builds and publishes the Hugo output under the repository base path.
• All current documentation sections and pages render successfully, including converted frontmatter and callout syntax.
• Existing public routes remain valid, or tested aliases/redirects preserve them.
• Navigation, sidebar behavior, syntax highlighting, callouts, search, edit links, repository links, and footer are present and usable.
• Search works in the deployed /grizzle/ base-path configuration without requiring a Node.js/npm build step.
• Automated generated-site link validation reports no broken internal links.
• VitePress configuration and documentation-only Node/npm dependencies are removed once parity is established.
• Local contributor instructions cover build, preview, link validation, and intentional Hugo upgrades.
• Generated site output is not committed to version control.

Validation plan

• Build from a clean checkout using the exact pinned Hugo version used in CI.
• Build and preview both a root-path local configuration and the GitHub Pages /grizzle/ base-path configuration.
• Run an automated link checker against the generated site.
• Compare the generated route inventory with the current published route inventory.
• Smoke-test representative pages from every navigation section, callouts, code blocks, search results, edit links, and mobile navigation.
• Validate the updated Actions workflow and smoke-test the deployed GitHub Pages site after merge.

References

• Current site configuration: docs/.vitepress/config.ts
• Current deployment workflow: .github/workflows/deploy-docs.yml
• Hugo documentation
• Hugo GitHub Pages deployment guidance
• Hugo search integrations