설정 가이드

게시물 정보

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

모든 설정은 docs/.vitepress/composables/options.ts의 configOptions 객체에서 관리합니다. config.mts에서 이 객체를 import하여 autoGenerateConfig()에 전달합니다.

// docs/.vitepress/config.mts
import { autoGenerateConfig } from './composables/index.ts';
import { configOptions } from './composables/options.ts';

const { nav, sidebar } = autoGenerateConfig(configOptions);

전체 옵션 목록

옵션	타입	기본값	설명
docsDir	string	'docs/src'	탐색 기준 디렉토리 (cwd 기준 상대)
navExclude	string[]	['public', '.vitepress']	Nav 탐색 제외 폴더명
sidebarExclude	string[]	['public', '.vitepress']	Sidebar 탐색 제외 폴더명
textMap	Record<string, string>	{}	경로별 표시 텍스트 직접 지정
maxNavDepth	number	2	Nav 탐색 최대 깊이 (VitePress 제약상 2 고정 권장)
navOrder	string[]	[]	Nav 폴더 표시 순서 (폴더명 배열)
showFolderIcon	boolean	true	폴더 아이콘 전역 on/off
folderIcons	FolderIconConfig	—	경로별 아이콘 커스터마이징
navFoldersOnly	boolean	false	true이면 Nav에 폴더만 표시
sidebarDepth	number	2	Sidebar 키 분할 깊이
sidebarSort	SidebarSortConfig	—	정렬 설정

docsDir · navExclude · sidebarExclude

docsDir: 'docs/src',
navExclude:     ['_part', 'public', '_bak'],
sidebarExclude: ['_part', 'public', '_bak'],

docsDir은 process.cwd() 기준 상대 경로입니다. 패키지 루트에서 실행한다고 가정합니다.

_로 시작하는 폴더명은 탐색 시 자동으로 건너뜁니다(.으로 시작하는 폴더도 동일). navExclude·sidebarExclude는 이에 더해 명시적으로 제외할 폴더명을 지정합니다.

navExclude와 sidebarExclude를 다르게 설정하면 Nav에는 표시하지 않지만 Sidebar에는 포함하는 폴더를 만들 수 있습니다.

navOrder · maxNavDepth · navFoldersOnly

navOrder: ['requests', 'guides', 'spec'],
maxNavDepth: 2,
navFoldersOnly: true,

navOrder: 배열에 지정된 폴더명이 Nav 왼쪽부터 순서대로 배치됩니다. 목록에 없는 폴더는 rootFolderSort 방식으로 정렬된 후 뒤에 추가됩니다.

maxNavDepth: VitePress Nav는 구조적으로 최대 2-depth만 허용합니다. 이 값을 2 이상으로 설정해도 VitePress 타입 제약으로 인해 3단계 이상은 렌더링되지 않습니다. 2로 고정하는 것을 권장합니다.

navFoldersOnly: true이면 파일 항목이 Nav에 나타나지 않습니다. docs/src/ 구조가 폴더 중심으로 구성된 경우 권장합니다.

textMap — 표시 텍스트 직접 지정

textMap: {
  '/policy-news/': '정책 뉴스',
  '/policy-news/2026/06/환경부 공지사항': '환경부',
},

키는 웹 경로입니다. 폴더는 trailing slash를 포함하고, 파일은 포함하지 않습니다. 지정된 경우 H1·파일명 변환보다 우선 적용됩니다.

sidebarDepth — 키 분할 깊이

sidebarDepth: 2,

Sidebar 키가 분할되는 깊이를 설정합니다. 파일 목록의 표시 깊이와는 다릅니다.

sidebarDepth: 1 — 최상위 폴더 단위로 키가 생성됩니다.

/policy-news/ 의 어느 페이지를 열어도 동일한 Sidebar 표시

sidebarDepth: 2 — 2단계 폴더 단위로 키가 생성됩니다.

/policy-news/2026/  Sidebar ─ 2026년 하위 폴더·파일 목록
/policy-news/2025/  Sidebar ─ 2025년 하위 폴더·파일 목록

월별·연별로 콘텐츠가 분리된 이 프로젝트 구조에서는 2가 적합합니다.

showFolderIcon · folderIcons — 아이콘 설정

showFolderIcon: true,
folderIcons: {
  default: '🔖',
  paths: {
    '/requests/': '📢',
    '/guides/':   'ℹ️',
    '/docs/':     '📖',
  },
},

showFolderIcon: false 로 설정하면 아이콘이 전체 비활성화됩니다. folderIcons 설정은 무시됩니다.

folderIcons.default: 지정된 경로에 해당하지 않는 모든 폴더에 적용되는 기본 아이콘. 비워두면 📁가 사용됩니다.

folderIcons.paths: 웹 경로별 아이콘을 지정합니다.

설정값	결과
'/requests/': '📢'	해당 경로에 📢 표시
'/law/': null	아이콘 없이 텍스트만 표시
'/etc/': '' 또는 생략	default 아이콘 사용

아이콘 상속: paths에 지정된 경로의 하위 폴더는 부모 경로의 아이콘을 자동 상속합니다.

paths: { '/guides/': 'ℹ️' }
// /guides/intro/      → ℹ️ (상속)
// /guides/advanced/   → ℹ️ (상속)

특정 하위 경로만 다르게 지정하면 해당 경로만 덮어씁니다.

paths: {
  '/guides/':          'ℹ️',
  '/guides/advanced/': '🚀',  // 이 경로만 다른 아이콘
}

sidebarSort — 정렬 설정

sidebarSort: {
  defaultFiles:   'alpha-asc',
  defaultFolders: 'alpha-desc',
  dateFields: ['date'],
  showDate: true,
  rules: {
    // '/docs/': { files: 'date-desc', showDate: true },
  },
},

정렬 메서드 종류

파일 정렬 (FileSortMethod)

값	기준	설명
alpha-asc	표시 텍스트(title)	오름차순 (기본값)
alpha-desc	표시 텍스트(title)	내림차순
name-asc	실제 파일명(.md 포함)	오름차순
name-desc	실제 파일명(.md 포함)	내림차순
date-asc	frontmatter 날짜	오름차순. 날짜 없는 파일은 후순위
date-desc	frontmatter 날짜	내림차순. 날짜 없는 파일은 후순위

폴더 정렬 (FolderSortMethod)

값	기준	설명
alpha-asc	표시 텍스트(title)	오름차순 (기본값)
alpha-desc	표시 텍스트(title)	내림차순
name-asc	실제 폴더명	오름차순
name-desc	실제 폴더명	내림차순

dateFields — 날짜 필드 우선순위

date-asc / date-desc 정렬 시 읽을 frontmatter 필드 목록입니다. 배열 순서대로 탐색하여 값이 있는 첫 번째 필드를 사용합니다.

dateFields: ['date', 'updated', 'created']
// → date가 없으면 updated, 그것도 없으면 created 사용

showDate — 날짜 prefix 표시

true이면 날짜 기준 정렬 시 Sidebar 항목 앞에 MM-DD | prefix가 붙습니다.

06-01 | 환경부 공지사항
06-03 | 기획재정부 보도자료

경로별로 showDate를 개별 설정할 수 있습니다.

rules: {
  '/diary/': { files: 'date-desc', showDate: true  },
  '/docs/':  { files: 'date-desc', showDate: false },  // 날짜 prefix 숨김
},

전역 showDate: false이면 경로별 showDate: true 설정도 무시됩니다.

rules — 경로별 정렬 규칙

특정 경로에만 다른 정렬을 적용합니다. 지정하지 않은 필드는 전역 기본값을 사용합니다.

rules: {
  '/policy-news/': { files: 'date-desc', showDate: true },
  '/docs/':        { folders: 'name-asc' },
}

하위 경로는 가장 가까운 부모 경로의 규칙을 상속합니다.

rules: { '/policy-news/': { files: 'date-desc' } }
// /policy-news/2026/  →  date-desc 상속
// /policy-news/2025/  →  date-desc 상속