hns-oss-docs-structure-map

docs-site Structure Map

Hugo geekdoc site at docs-site/, deployed to adk.mo.ai.kr via Vercel (auto-deploy on push). All paths below are relative to docs-site/.

Path map

Surface	Path	Notes
Site config	`hugo.toml`	NOT hugo.yaml. `defaultContentLanguage = "ko"`; version SSOT `params.version` / `params.releaseDate`
Content	`content/{ko,en,ja,zh}/`	ko canonical; 4 locale trees mirror each other
Section order	`content/<locale>/_meta.yaml`	per-locale; a section change lands in ALL FOUR files
Sidebar menu	`data/menu/main.yaml`	4-locale name maps + `icon:` per entry
Menu icons	`layouts/partials/menu.html`	SVG `switch`/case per `icon:` value — coupling below
Shortcodes	`layouts/shortcodes/`	`icon.html` (variants ok/warn/danger/primary/muted), etc.
CSS	`static/moai-brand.css` (FROZEN — never edit), `static/moai-design.css`	Claude Warm Editorial, light-only theme
Redirects	`vercel.json`	`redirects` array — the only Vercel surface this harness touches

main.yaml entry schema

Each sidebar entry carries a 4-locale name map and an icon:

- name:
    ko: 시작하기
    en: Getting Started
    ja: はじめに
    zh: 快速开始
  ref: /getting-started
  icon: rocket

icon ↔ menu.html SVG-case coupling [HARD]

Every icon: value in main.yaml MUST have a matching case in the SVG switch inside layouts/partials/menu.html. An unmatched value renders an empty <svg> — a silent visual defect (no build warning). After any icon edit:

grep -n '"<icon-value>"' docs-site/layouts/partials/menu.html

If absent, add the SVG path case in the same change.

vercel.json redirect pattern

Moved/renamed pages require BOTH entries:

{
  "redirects": [
    { "source": "/:locale(ko|en|ja|zh)/old-path", "destination": "/:locale/new-path" },
    { "source": "/old-path", "destination": "/ko/new-path" }
  ]
}

The Vercel project binding itself is immutable — this harness edits only the redirects array.

Known divergence to reconcile

content/<locale>/_meta.yaml carries a design section while data/menu/main.yaml carries guides. When touching either file, reconcile toward the SSOT design report's 12→11 section restructure (.moai/reports/readme-docs-redesign-20260713.md) and record the resolution direction in your report.

Tooling reality

gen_menu.py (referenced by the legacy i18n rules doc) DOES NOT exist — menu edits are manual; use the coupling grep above.
Build check: cd docs-site && hugo --minify --gc must complete warning-free (a malformed _meta.yaml or menu entry surfaces here). Full recipe: Skill("hns-oss-docs-verify").