Skip to content

Migrate docs site to Hugo Hinode#21

Merged
adonm merged 2 commits into
mainfrom
oy/hugo-hinode
May 5, 2026
Merged

Migrate docs site to Hugo Hinode#21
adonm merged 2 commits into
mainfrom
oy/hugo-hinode

Conversation

@adonm

@adonm adonm commented May 5, 2026

Copy link
Copy Markdown
Contributor

Summary

  • migrate the documentation site from mdBook to Hugo using Hinode as a Hugo module
  • move Markdown into the standard content/docs/ Hugo structure with front matter and section indexes
  • preserve the old mdBook/SUMMARY navigation order with Hugo weights and printable ordering
  • preserve mdBook-style public URLs such as /security/001-isolation.html, /operations/010-configmgmt.html, /CONTRIBUTING.html, /compliance-mapping.html, and /glossary.html
  • keep /docs/.../ aliases for backwards compatibility while generated navigation and sampled page links avoid /docs/ URLs
  • convert D2 diagrams to Mermaid code fences and enable Hinode Mermaid rendering
  • replace the generated release PDF with a /printable/ long-page print/save-as-PDF view
  • simplify site chrome: text title instead of Hinode logo, no copyright footer, no GitHub/social footer, and hidden navbar/footer chrome in print output
  • manage Hugo Extended, Sass, and Cargo-installed tooling through mise (hugo-extended, npm:sass-embedded, cargo-binstall, cargo:rumdl)
  • update CI, build tooling, ignores, README, and content checks for Hugo

Reviewer notes

  • The large diff is mostly the expected mdBook-to-Hugo content move plus front matter and URL/link updates.
  • Generated output is intentionally not committed; public/, resources/, hugo_stats.json, and .hugo_build.lock are clean.
  • Custom layout overrides are intentionally small and localised:
    • layouts/_default/printable.html
    • layouts/index.html
    • layouts/_partials/assets/breadcrumb.html
    • layouts/_partials/footer/footer.html
    • layouts/_partials/footer/social.html
    • layouts/_partials/utilities/GetPage.html

Validation

  • python3 scripts/check-content.py
  • mise exec -- hugo --minify
  • git diff --cached --check
  • verified docs and printable page order: intro, architecture principles, security, operations, development, reference architectures, templates, contributing, compliance, glossary
  • verified mdBook-compatible generated output paths exist, including representative ADRs and top-level pages
  • verified generated page links sampled from home and ADR pages do not point at /docs/
  • verified printable output has no footer/social chrome and no copyright footer text
  • verified Mermaid markup and runtime assets are present in generated ADR and printable pages

Notes

  • Supersedes Migrate docs site to Hugo Hinode #20, whose old source branch was removed during the requested branch rename/history cleanup.
  • Hugo emits upstream Hinode/module deprecation warnings for module.mounts.includeFiles, .Site.Data, and .Site.Languages; the build completes successfully.
  • lychee reports redirects only; no link errors.

@adonm adonm force-pushed the oy/hugo-hinode branch 8 times, most recently from cac19b7 to 825e66a Compare May 5, 2026 04:54
@adonm adonm force-pushed the oy/hugo-hinode branch from 825e66a to fcd41d7 Compare May 5, 2026 05:01
@adonm adonm merged commit 4787728 into main May 5, 2026
4 checks passed
@adonm adonm deleted the oy/hugo-hinode branch May 6, 2026 21:15
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