← LeaderboardThe Skill Leaderboard

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.

Published by modu-ai ↗modu-ai/moai-adk

Try your first task

Start a fresh conversation. Replace the highlighted placeholders.

Use hns-oss-docs-structure-map to identify the exact files, locale impacts, icon coupling, and redirect requirements for [planned docs navigation or configuration change], then provide a safe edit plan without changing frozen CSS or project binding.

Required inputs

[planned docs navigation or configuration change]

User-approved starter prompt based on a pinned source version; check current skill requirements before running. Task evidence ↗

SKILL.md

name: hns-oss-docs-structure-mapdescription: >  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, Bashuser-invocable: falsemetadata:   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").