hns-oss-docs-structure-map

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.

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

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

Repository: modu-ai/moai-adk
Path: .claude/skills/hns-oss-docs-structure-map/SKILL.md
Commit: 05117b6

Last updated: 1 day ago
First committed: 19 days ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.