hns-oss-docs-structure-map
GitHub提供 docs-site Hugo 站点的完整结构映射，涵盖配置、多语言内容、侧边栏菜单及图标耦合规则。用于指导导航与配置编辑，确保 i18n 一致性和部署正确性。
Trigger Scenarios
Install
npx skills add modu-ai/moai-adk --skill hns-oss-docs-structure-map -g -y
SKILL.md
Frontmatter
{
"name": "hns-oss-docs-structure-map",
"metadata": {
"tags": "oss-docs,docs-site,hugo,geekdoc,menu,redirects,structure",
"status": "active",
"updated": "2026-07-13",
"version": "1.0.0",
"category": "harness"
},
"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.\n",
"allowed-tools": "Read, Grep, Glob, Bash",
"user-invocable": false
}
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 --gcmust complete warning-free (a malformed_meta.yamlor menu entry surfaces here). Full recipe: Skill("hns-oss-docs-verify").
Version History
- 4100d87 Current 2026-08-20 09:07
