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