Skip to content

feat(site): Hugo + Docsy documentation site on GitLab Pages

Jérôme Revillard requested to merge feat/hugo-docs-site into main

What

Adds a Hugo + Docsy documentation site, published to GitLab Pages at https://genie-ai-7e342b.opensource.unicc.org/ (provisioned unique domain). Public landing page + curated docs for implementers and the internal team.

Design spec: docs/superpowers/specs/2026-06-29-hugo-docs-site-design.md · Plan: docs/superpowers/plans/2026-06-29-hugo-docs-site.md

What's added

  • site/ — self-contained Hugo project (Docsy theme via Hugo Module, pinned to /theme HEAD 93948e65e6c1). Full hugo.toml, Docsy-blocks landing page + about page, brand SCSS override + placeholder logo, README.
  • site/scripts/sync-docs.sh — curated copy of 5 repo-root docs/*.md → content/en/docs/ at build time. Source of truth stays docs/; copied output is gitignored. Zero drift.
  • .gitlab-ci.yml — adds one deploy stage + one pages: job (hugomods/hugo:exts, main-only, publishes public/). No collateral edits to existing lint/test/build/scan/e2e stages.

Tech choices

  • Hugo extended + Docsy /theme (Hugo Module), Node/npm for Docsy's PostCSS pipeline.
  • English-only at launch; i18n scaffolding in place (content/en/, defaultContentLanguage=en) — adding a language is additive.
  • Targets latest stable (Hugo 0.163.3 locally; CI hugomods/hugo:exts).
  • Doc content is mounted via build-time copy, never committed twice.

CI

New pages job runs on main after the existing stages. First publish lands when this MR merges.

Verification

Every task was implemented + individually code-reviewed (TDD-style build-verify gates), then a final whole-branch review (2 onboarding/accuracy fixes applied: README npm install step, go.mod comment). Clean local build: landing + about + 5 docs + robots.txt + sitemap.xml; no internal scratch leaked.

Post-merge

  • Site goes live at the provisioned Pages URL once main builds.
  • Squash-merge enabled (commit history tidied at merge).

Out of scope (follow-ups)

Pin CI image to a tag for reproducibility; artifacts.expire_in; i18n stub; custom domain; translations; version dropdown.

Merge request reports