---
name: HNS OSS Docs Structure Map
slug: hns-oss-docs-structure-map
category: Writing
description: HNS OSS Docs Structure Map documents exact paths and schemas for the HNS OSS docs site, including Hugo config, locale metadata, sidebar menu icons, and Vercel redirects. Use it before editing navigation or configuration in the docs-site so changes stay consistent across all four locales.
github: "https://github.com/modu-ai/moai-adk/tree/main/.claude/skills/hns-oss-docs-structure-map"
language: Go
stars: 1177
forks: 220
install: "npx degit https://github.com/modu-ai/moai-adk/tree/main/.claude/skills/hns-oss-docs-structure-map ~/.claude/skills/hns-oss-docs-structure-map"
installs_to: ~/.claude/skills/hns-oss-docs-structure-map
source_path: .claude/skills/hns-oss-docs-structure-map/SKILL.md
collection_size: 25
category_size: 1012
collection_url: "https://dirskills.com/collections/modu-ai/moai-adk"
added: 2026-08-20T07:55:48.672Z
last_synced: 2026-08-20T07:55:48.672Z
canonical_url: "https://dirskills.com/skills/hns-oss-docs-structure-map"
---

# HNS OSS Docs Structure Map

HNS OSS Docs Structure Map documents exact paths and schemas for the HNS OSS docs site, including Hugo config, locale metadata, sidebar menu icons, and Vercel redirects. Use it before editing navigation or configuration in the docs-site so changes stay consistent across all four locales.

**Install:**

```bash
npx degit https://github.com/modu-ai/moai-adk/tree/main/.claude/skills/hns-oss-docs-structure-map ~/.claude/skills/hns-oss-docs-structure-map
```

## README

# 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:

```yaml
- 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:

```bash
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:

```json
{
  "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").