hns-oss-docs-structure-map

name	hns-oss-docs-structure-map
description	docs-site structure map for the oss-docs harness structure-curator: exact paths and schemas for hugo.toml, per-locale content/<locale>/_meta.yaml, data/menu/main.yaml (4-locale name maps + icon values), the icon-to-SVG-case coupling in layouts/partials/menu.html, shortcodes, the FROZEN moai-brand.css, vercel.json redirect examples, and the known design-vs-guides divergence. Loaded by the structure-curator before any navigation or config edit.
allowed-tools	Read, Grep, Glob, Bash
user-invocable	false
metadata	{"version":"1.0.0","category":"harness","status":"active","updated":"2026-07-13","tags":"oss-docs,docs-site,hugo,geekdoc,menu,redirects,structure"}

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