​

사이드바/네비게이션 관리 스킬

​

docs.json 구조

{
  "navigation": {
    "versions": [
      {
        "version": "Korean",
        "tabs": [
          {
            "tab": "Porter AI",
            "groups": [
              { "group": "도입 판단", "pages": ["ko/introduction", "ko/security"] }
            ]
          }
        ]
      }
    ]
  }
}

• pages 항목은 확장자 없는 경로 문자열 (ko/introduction).
• pages 안에 중첩 그룹 객체 { "group": "...", "pages": [...] } 를 넣을 수 있다 (애플리케이션 플랫폼 탭의 “애플리케이션 배포 예제” > Python/Node.js 참고).

​

카테고라이징 원칙 (AGENTS.md 5원칙의 상세)

​

원칙 1: 독자 여정 순서

​

원칙 2: 그룹명은 독자 과업 중심 한국어

• 명사구, 대략 2~15자 (“내부 데이터와 지식베이스 활용” ○ / “Integrations” ✕ / “기타” ✕)
• 개발자 대상 탭의 영문 관례(Getting Started, CLI)는 예외로 허용.

​

원칙 3: 고아 파일 금지 — 아래 검사 스크립트로 확인

​

원칙 4: 기존 그룹 우선, 그룹 신설은 3기준 충족 시만

1. 배치할 페이지가 3개 이상이고,
2. 기존 어느 그룹의 과업 정의에도 들어맞지 않으며,
3. 여정상 위치를 한 문장으로 설명할 수 있을 때.

​

새 페이지 배치 결정 절차

• Q1. 주 독자는 누구인가?
  • 도입 의사결정자 → Porter AI 탭 “도입 판단” 또는 “엔터프라이즈 거버넌스”
  • 일반 사용자 → “업무 AI 활용”
  • 개발자 → “사내 지식과 시스템 연결” 또는 애플리케이션 플랫폼 탭
  • AI 전문가 → “모델과 에이전트 확장”
  • 관리자 → “엔터프라이즈 거버넌스” 또는 운영 시스템 탭
• Q2. 여정의 어느 단계인가? → 탭·그룹 확정
• Q3. 그룹 내 어디에 두는가? → 이 페이지가 요구하는 선행 지식을 다루는 페이지 뒤에 배치
• Q4. 기존 페이지와 주제가 겹치는가? → 겹치면 신설 대신 기존 페이지 확장을 먼저 검토 (중복 부채 방지 — doc-review 스킬의 known-issues.md 참고)

​

고아 파일 검사

python3 - <<'EOF'
import json, glob, os
d = json.load(open('docs.json'))
reg = set()
def walk(o):
    if isinstance(o, dict):
        for p in o.get('pages', []):
            reg.add(p) if isinstance(p, str) else walk(p)
        for k in ('versions', 'tabs', 'groups'):
            walk(o.get(k, []))
    elif isinstance(o, list):
        for i in o: walk(i)
walk(d['navigation'])
files = {os.path.splitext(f)[0] for f in glob.glob('ko/**/*.mdx', recursive=True)}
files |= {os.path.splitext(f)[0] for f in glob.glob('*.mdx')}
print("고아 파일:", sorted(files - reg))
print("등록됐지만 파일 없음:", sorted(reg - files))
EOF

• 2026-07-28 기준 고아 28개가 .claude/skills/doc-review/known-issues.md 에 기록돼 있다. 검사 결과가 28개보다 늘었다면 새 고아가 생긴 것 — 등록하거나 브랜치로 뺀다.
• 그중 ko/ops/* 14개는 의도적 비공개라 기준선에 포함돼 있다. 등록 대상으로 오해하지 말 것.
• 이 스크립트는 ko/ 와 루트만 스캔한다. license/license.mdx, snippets/snippet-intro.mdx 는 집계에서 빠지므로 저장소 전체 find 기준(30개)과 2건 차이가 난다.
• “등록됐지만 파일 없음”이 나오면 사이트 빌드가 깨지므로 즉시 수정.

​

작업 후 검증

1. 위 고아 검사 스크립트 재실행 — 새 고아·누락 0 확인
2. mintlify broken-links — 내부 링크 검사
3. mintlify dev 로 사이드바 렌더링 확인 (그룹명, 순서, 아이콘)