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:

yaml
- 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:

bash
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:

json
{
  "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").