모듈 역할과 의존 관계

게시물 정보

• 작성일: 2026년 6월 8일 월요일 (약 1개월 전)
• 글쓴이: claude.ai
• 주제어: #기술 문서 #운영 매뉴얼 #claude.ai #모듈 역할과 의존 관계

각 파일의 책임 범위와 수정 시 주의사항을 설명합니다.

index.ts — 공개 진입점

autoGenerateConfig(options)를 export합니다. config.mts에서 호출하는 유일한 공개 API입니다.

주요 역할

• 옵션 기본값 적용
• clearFrontmatterCache() 호출 (빌드마다 캐시 초기화)
• Nav용 traverseDirectory 호출 후 buildNav에 전달
• Sidebar용 buildSidebar 호출
• { nav, sidebar } 반환

수정 시 주의: Nav와 Sidebar가 동일한 traverseDirectory 결과를 공유하지 않습니다. Nav는 maxNavDepth가 적용된 별도 탐색 결과를 사용하고, Sidebar는 buildSidebar 내부에서 독립적으로 탐색합니다.

options.ts — 사용자 설정

configOptions 객체를 export합니다. 설정을 변경할 때 이 파일만 수정합니다. 코드 로직을 건드리지 않아도 됩니다.

설정 항목 상세

core/types.ts — 타입 정의

시스템 전체에서 사용하는 타입을 한 곳에서 관리합니다.

핵심 타입 목록

타입	설명
NavItem · SidebarItem · SidebarMulti	VitePress DefaultTheme 타입 재export
FileSortMethod	파일 정렬 메서드 유니언 타입
FolderSortMethod	폴더 정렬 메서드 유니언 타입
SidebarSortConfig	sidebarSort 옵션 전체 구조
SidebarSortRules	경로별 정렬 규칙 구조
FolderIconConfig	아이콘 설정 구조
FileMetadata	파일 경로·이름·날짜 메타데이터
TraversedFileItem · TraversedDirItem	탐색 결과 항목
AutoConfigOptions	autoGenerateConfig 옵션 전체 구조
GeneratedConfig	{ nav, sidebar } 반환 타입

VitePress 공식 타입을 직접 사용합니다. 자체 정의 시 config.mts 주입 지점에서 타입 불일치 오류가 발생합니다.

core/constants.ts — 기본값 상수

옵션의 기본값을 상수로 관리합니다.

상수	값	의미
DEFAULT_DOCS_DIR	'docs/src'	탐색 기준 디렉토리
DEFAULT_EXCLUDES	['public', '.vitepress']	기본 제외 폴더
DEFAULT_MAX_NAV_DEPTH	2	Nav 탐색 최대 깊이
DEFAULT_SIDEBAR_DEPTH	2	Sidebar 키 분할 깊이
DEFAULT_DATE_FIELDS	['date']	날짜 필드 기본값
DEFAULT_SORT.files	'alpha-asc'	파일 기본 정렬
DEFAULT_SORT.folders	'alpha-asc'	폴더 기본 정렬

core/iconResolver.ts — 아이콘 결정

resolveIcon(webPath, config, enabled) 함수 하나를 export합니다.

결정 우선순위:

1. config.paths에 해당 경로가 직접 지정된 경우
2. 없으면 가장 가까운 부모 경로 상속
3. 부모도 없으면 config.default 또는 📁 사용

반환값: 아이콘 문자열 + 공백 한 칸 (예: '📢 '). 아이콘이 없어야 하면 ''. enabled: false이면 무조건 ''.

수정 시 주의: 반환값에 trailing space가 포함되어 있습니다. 호출 측에서 별도 공백을 추가하지 않도록 합니다.

builders/navBuilder.ts — Nav 조립

buildNav(options) 함수를 export합니다. TraversedItem[]을 VitePress NavItem[]으로 변환합니다.

depth 구조

depth-1: NavItemWithLink | NavItemWithChildren
depth-2: NavItemWithLink | NavItemChildren   ← NavItemWithChildren 사용 불가

navFoldersOnly: true이면 depth-1·2 모두에서 파일 항목이 필터링됩니다. depth-2의 폴더는 하위 파일이 없으므로 NavItemChildren 분기에 진입하지 않고 hasIndex 기반 링크로만 변환됩니다.

Nav에 항목이 나타나지 않는 경우:

• 폴더에 index.md가 없고 하위 항목도 없는 경우 → null 반환 후 필터링됨
• navFoldersOnly: true인데 파일만 있는 폴더인 경우

builders/sidebarBuilder.ts — Sidebar 조립

buildSidebar(docsDirPath, options) 함수를 export합니다. SidebarMulti 객체를 생성합니다.

sidebarDepth 동작

registerEntries가 재귀적으로 호출되며, currentDepth < targetDepth인 동안은 SidebarMulti 키를 등록하지 않고 하위 폴더로 내려갑니다. currentDepth === targetDepth에 도달했을 때 해당 경로를 키로 등록합니다.

sidebarDepth: 2, 폴더 구조: /policy-news/2026/06/
  currentDepth=1 (/policy-news/)    → 등록 안 함, 하위로 진입
  currentDepth=2 (/policy-news/2026/) → 키 등록: sidebar['/policy-news/2026/']

수정 시 주의: 최상위 그룹은 collapsed: false로, 하위 폴더 항목은 collapsed: true로 설정됩니다. 이 동작을 변경하려면 registerEntries의 최상위 객체와 toSidebarItem의 SidebarItem 생성 부분을 각각 수정해야 합니다.

traversal/directoryTraverser.ts — 디렉토리 탐색

traverseDirectory(dirPath, options) 함수를 export합니다. 주어진 디렉토리를 재귀 탐색하여 TraversedItem[]을 반환합니다.

처리 순서: 폴더 먼저, 파일 나중 (각각 정렬 후 배열에 push)

혼재 감지: 같은 레벨에 폴더와 파일이 공존하면 console.error로 경고를 출력하고 파일을 무시합니다. 빌드는 계속 진행되지만 해당 레벨의 파일이 Nav·Sidebar에서 누락됩니다.

maxDepth: undefined이면 깊이 제한 없이 탐색합니다. Nav 생성 시에는 maxNavDepth가 전달되고, Sidebar 생성 시에는 생략됩니다.

metadata/frontmatterParser.ts — frontmatter 파싱

getFrontmatterDates(filePath) · createFileMetadata(filePath, sortMethod, dateFields) · clearFrontmatterCache()를 export합니다.

캐시 구조: Map<filePath, FrontmatterCacheItem>으로 관리합니다. date 필드만 캐시하며, 복수 dateFields 사용 시에는 매번 파일을 직접 읽습니다.

날짜 파싱: utils/timeUtils.ts의 parseUTC()를 사용합니다. YYYY-MM-DD 형식은 UTC 자정으로, 타임존 없는 ISO 형식은 UTC로 해석합니다.

수정 시 주의: date-asc / date-desc 이외의 정렬 메서드로 호출할 때는 createFileMetadata가 날짜를 파싱하지 않습니다. 불필요한 파일 I/O를 최소화하기 위한 의도적인 설계입니다.

metadata/titleResolver.ts — 표시 제목 결정

getFolderTitle(dirPath, webPath, textMap) · getFileTitle(filePath, webPath, textMap)를 export합니다.

H1 추출: 코드 펜스(```` )와 frontmatter를 제거한 후 첫 번째 # 제목을 추출합니다. 코드 블록 안의 #이 제목으로 잘못 인식되는 것을 방지합니다.

sort/fileSorter.ts — 정렬 실행

sortFiles(files, method) · sortFolders(folders, method)를 export합니다. 정렬 메서드에 따라 배열을 정렬하여 반환합니다.

날짜 없는 파일의 처리: date-asc / date-desc 정렬 시 날짜가 없는 파일은 항상 목록 맨 뒤에 배치되며, 날짜 없는 파일끼리는 basename 알파벳 순으로 정렬됩니다.

sort/sortRuleResolver.ts — 정렬 규칙 결정

resolveSortRules(webPath, rules, defaultFiles, defaultFolders) 함수를 export합니다.

경로 정규화(normalizeWebPath)를 수행하므로 trailing slash 유무에 관계없이 동일하게 처리됩니다.

showDate 반환값: 경로 규칙에 지정된 경우 해당 boolean, 없으면 undefined를 반환합니다. 호출 측에서 resolved.showDate ?? globalShowDate로 전역 기본값과 병합합니다.

utils/pathUtils.ts — 경로 변환

함수	설명
toWebPath(fsPath, baseDir, isDir)	절대 파일 경로 → VitePress 웹 경로
resolveFromCwd(relativePath)	상대 경로 → process.cwd() 기준 절대 경로

utils/textUtils.ts — 텍스트 변환

nameToText(name): kebab-case · snake_case 이름을 Title Case로 변환합니다.

'policy-news'  →  'Policy News'
'2026_june'    →  '2026 June'

utils/timeUtils.ts — 날짜 유틸

함수	설명
parseUTC(dateInput)	문자열·Date → UTC 기준 Date 객체
formatDate(date)	Date → 'MM-DD' 문자열

parseUTC는 YYYY-MM-DD 형식을 T00:00:00Z(UTC 자정)으로 해석합니다. 로컬 타임존에 따라 날짜가 하루 밀리는 문제를 방지합니다.

usePostData.ts — Vue 컴포저블

VitePress 컴포넌트에서 frontmatter 데이터를 사용할 때 import하는 컴포저블입니다. Nav·Sidebar 생성 로직과는 독립적입니다.

제공 데이터

반환값	타입	설명
writers	ComputedRef<string>	frontmatter.writers 배열을 쉼표 구분 문자열로 변환. 없으면 '무명'
tags	ComputedRef<string[]>	frontmatter.tags. 없으면 []
runningInfo	ComputedRef<any>	frontmatter.runningInfo. 없으면 null
postDate	ComputedRef<string|null>	frontmatter.date. 없으면 null
frontmatter	Ref	VitePress useData().frontmatter 원본

사용 예:

<script setup>
import { usePostData } from '../composables/usePostData.ts'
const { writers, tags, postDate } = usePostData()
</script>