동작 원리

게시물 정보

• 작성일: 2026년 6월 8일 월요일 (약 1개월 전)
• 글쓴이: claude.ai
• 주제어: #기술 문서 #운영 매뉴얼 #claude.ai #동작 원리

autoGenerateConfig()가 호출되는 순간부터 VitePress용 객체가 완성되기까지의 전체 흐름을 설명합니다.

전체 흐름

config.mts
  autoGenerateConfig(configOptions)
         │
         │ 1. clearFrontmatterCache()
         │
         ├─── Nav 생성 ────────────────────────────────────────────────
         │    traverseDirectory(docsDirPath, { maxDepth: maxNavDepth })
         │         ↓
         │    TraversedItem[]  (최대 2-depth)
         │         ↓
         │    buildNav({ items, navOrder, ... })
         │         ↓
         │    NavItem[]
         │
         └─── Sidebar 생성 ────────────────────────────────────────────
              buildSidebar(docsDirPath, options)
                   │
                   │ docs/src/ 의 최상위 폴더 목록 취득 (navOrder 순서 적용)
                   │
                   └─ 폴더별 반복 ──────────────────────────────────────
                        traverseDirectory(folderPath, { /* maxDepth 없음 */ })
                             ↓
                        TraversedItem[]  (깊이 제한 없음)
                             ↓
                        registerEntries → SidebarMulti 키에 등록
                             ↓
                        SidebarMulti  { '/folder/': [SidebarItem] }

단계별 상세

1단계 — 캐시 초기화

clearFrontmatterCache()로 이전 빌드의 frontmatter 파싱 결과를 비웁니다. Hot reload 시 오래된 날짜 데이터가 잔류하는 것을 방지합니다.

2단계 — 디렉토리 탐색 (directoryTraverser.ts)

docs/src/ 전체를 재귀 탐색하여 TraversedItem[]을 반환합니다.

각 항목은 두 가지 타입 중 하나입니다.

TraversedFileItem  { type: 'file', name, path, webPath, title, metadata }
TraversedDirItem   { type: 'dir',  name, path, webPath, title, children, hasIndex }

탐색 중 폴더와 파일이 같은 레벨에 혼재하면 경고를 출력하고 해당 레벨의 파일을 건너뜁니다. 동일 디렉토리 내에 폴더와 Markdown 파일을 함께 두지 않아야 합니다.

index.md는 탐색 대상 파일에서 제외됩니다. 폴더의 hasIndex: true 여부 판별에만 사용됩니다.

3단계 — 제목 결정 (titleResolver.ts)

파일·폴더의 표시 제목은 다음 우선순위로 결정됩니다.

1. textMap[webPath]          ← options.ts에서 직접 지정한 텍스트
2. index.md 또는 파일의 H1   ← Markdown 첫 번째 # 제목
3. nameToText(폴더명·파일명)  ← kebab/snake → Title Case 자동 변환

예) policy-news → Policy News, 2026_june → 2026 June

4단계 — 정렬 (sortRuleResolver.ts · fileSorter.ts)

정렬 규칙은 경로 기준으로 결정됩니다.

1. rules[정확한 webPath]    ← options.ts sidebarSort.rules 직접 지정
2. rules[가장 가까운 부모]   ← 상속
3. defaultFiles / defaultFolders  ← 전역 기본값

date-asc / date-desc 사용 시 frontmatter의 dateFields 필드를 순서대로 탐색하여 값이 존재하는 첫 번째 날짜를 정렬 기준으로 사용합니다.

5단계 — Nav 조립 (navBuilder.ts)

VitePress Nav는 최대 2-depth 제약이 있습니다.

depth	가능한 타입
1	NavItemWithLink · NavItemWithChildren
2	NavItemWithLink · NavItemChildren (WithChildren 불가)

navOrder에 지정된 폴더가 먼저 배치되고, 나머지는 rootFolderSort 방식으로 정렬됩니다. navFoldersOnly: true이면 파일 항목은 Nav에서 제외됩니다.

폴더가 Nav에 표시되려면 다음 조건 중 하나를 충족해야 합니다.

• 하위 항목(파일 또는 폴더)이 존재하거나
• index.md가 있어 hasIndex: true인 경우

6단계 — Sidebar 조립 (sidebarBuilder.ts)

SidebarMulti 형식으로 조립됩니다. 각 최상위 폴더가 하나의 키가 됩니다.

{
  '/policy-news/': [{ text: '🔖 Policy News', link: '/policy-news/', items: [...], collapsed: false }],
  '/guides/':      [{ text: 'ℹ️ Guides',       link: '/guides/',       items: [...], collapsed: false }],
}

sidebarDepth는 Sidebar의 키 분할 깊이를 결정합니다. 파일 목록 표시 깊이가 아닙니다.

sidebarDepth	동작
1	최상위 폴더(/policy-news/)가 키. 하위 폴더도 같은 Sidebar에 중첩 표시
2	2단계 폴더(/policy-news/2026/)가 키. 각 하위 폴더가 독립적인 Sidebar 영역

디렉토리 구조 설계 원칙

이 시스템이 올바르게 동작하려면 docs/src/ 하위 디렉토리가 아래 원칙을 따라야 합니다.

원칙 1: 동일 레벨에 폴더와 파일 혼재 금지

❌ 잘못된 구조
docs/src/policy-news/
  ├── 2026/          ← 폴더
  └── overview.md   ← 파일  → 경고 출력 후 overview.md 무시됨

✅ 올바른 구조 A — 파일만
docs/src/policy-news/
  ├── index.md
  └── overview.md

✅ 올바른 구조 B — 폴더만
docs/src/policy-news/
  ├── index.md
  └── 2026/
        └── 06/

원칙 2: index.md는 폴더 대표 페이지

index.md는 탐색 목록에 포함되지 않습니다. 폴더의 hasIndex 플래그와 H1 제목 추출에만 사용됩니다. Nav·Sidebar에서 폴더에 링크를 부여하려면 index.md가 있어야 합니다.

원칙 3: 제외 폴더 관리

navExclude · sidebarExclude에 지정된 폴더는 탐색에서 제외됩니다. 기본값은 ['public', '.vitepress']이며, options.ts에서 ['_part', 'public', '_bak']으로 재정의하고 있습니다.