시작하기

이 페이지에서는 VitePress Sidebar 모듈의 설치 및 사용 방법을 안내합니다.

설치

먼저 이 모듈을 사용하기 전에 VitePress 모듈을 사전 구성해야 할 수 있습니다.

Node.js 버전은 22.x 이상을 사용하는 것이 좋습니다. VitePress Sidebar는 ESM으로 작성되었습니다. CommonJS 환경에서 사용하려면 여기 지침을 참조하세요.

NPM 또는 다른 노드 모듈 패키지 관리자를 사용하여 모듈을 설치할 수 있습니다. 이 패키지는 개발자 환경에서만 사용되므로 devDependencies에 설치해야 합니다. 아래 명령어로 설치하세요:

shell

# `npm`으로 설치
$ npm i -D vitepress-sidebar

# `yarn`으로 설치
$ yarn add -D vitepress-sidebar

# `pnpm`으로 설치
$ pnpm i -D vitepress-sidebar

동작 과정

VitePress Sidebar는 귀하의 프로젝트의 폴더에서 지정한 폴더 경로(documentRootPath)를 기준으로 폴더와 마크다운 파일을 계층별로 스캔합니다.

이후 설정에 따라 특정 파일을 제외, 정렬, 포맷팅하여 사이드바 메뉴의 제목을 읽어온 후 VitePress에서 요구하는 사이드바 스펙에 따라 설정 데이터를 최종적으로 출력하게 됩니다.

결과적으로는 VitePress의 config.js 파일은 다음과 같이 변환 될 것입니다.

javascript

export default {
  themeConfig: {
    sidebar: [
      // VitePress Sidebar의 출력 결과
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/introduction' },
          { text: 'Getting Started', link: '/getting-started' }
        ]
      }
    ]
  }
};

이로 인해 sidebar의 각 메뉴에 대한 수동 작성이 필요하지 않습니다.

사용 방법

VitePress Sidebar는 withSidebar와 generateSidebar 두가지 함수로 사이드 바를 자동으로 생성할 수 있습니다. 이 둘의 동작은 같지만 함수를 사용하는 위치가 다릅니다. 일반적으로는 핫 리로드를 지원하고 정석적인 방법인 withSidebar를 사용하는 것을 권장합니다.

설치한 모듈을 코드에 가져오려면 VitePress의 config.js 파일을 엽니다. 이 파일은 .vitepress 디렉토리에 위치하며 프로젝트에 따라 다른 확장자의 이름일 수 있으니 유의하시기 바랍니다.

파일을 열고 아래 두가지 방법 중 하나를 사용하여 vitepress-sidebar를 사용할 수 있습니다:

1. `withSidebar` 사용 (권장)

withSidebar는 defineConfig레벨에서 사용합니다. 이 때 주의할 점은 VitePress의 설정 객체가 첫번째 파라미터에, 이후 VitePress Sidebar의 옵션이 두번째 파라미터에 위치해야 합니다.

VitePress Sidebar는 기존 VitePress의 옵션에 필요한 추가 옵션을 오버라이딩 할 것입니다. 기존에 설정한 수동 sidebar 옵션은 새 옵션에 의해 무시됩니다.

또한 VitePress 설정의 srcExclude를 함께 읽으므로, 빌드에서 제외한 문서는 사이드바에도 표시되지 않으며 같은 경로를 두 번 제외할 필요가 없습니다.

javascript

// `.vitepress/config.js`
import { withSidebar } from 'vitepress-sidebar';

const vitePressOptions = {
  // VitePress의 옵션
  title: 'VitePress Sidebar',
  themeConfig: {
    // ...
  }
};

const vitePressSidebarOptions = {
  // VitePress Sidebar의 옵션
  documentRootPath: '/',
  collapsed: false,
  capitalizeFirst: true
};

export default defineConfig(withSidebar(vitePressOptions, vitePressSidebarOptions));

2. `generateSidebar` 사용

generateSidebar는 themeConfig.sidebar 레벨에서 사용할 수 있습니다. 이는 좀 더 세부적인 themeConfig 설정을 위해 코드 분리가 필요할 때 사용할 수 있습니다.

특수한 경우가 아닌 경우는 withSidebar를 사용하는 것을 권장합니다. generateSidebar는 문서가 추가 또는 삭제되면 서버를 재시작하지 않는 이상 즉시 사이드바가 업데이트되지 않습니다.

javascript

// `.vitepress/config.js`
import { generateSidebar } from 'vitepress-sidebar';

export default defineConfig({
  themeConfig: {
    sidebar: generateSidebar({
      // VitePress Sidebar의 옵션
    })
  }
});

VitePress Sidebar는 프로젝트의 문서를 스캔하기 위해 documentRootPath 옵션으로 작업 경로를 지정하여 올바른 위치를 알려주어야 합니다. 기본값은 /이지만 프로젝트에 따라 docs와 같이 별도의 폴더에 VitePress 프로젝트가 위치하는 경우에는 직접 경로를 지정해야 합니다.

프로젝트 루트 경로를 기준으로, documentRootPath의 경로는 .vitePress 폴더가 위치한 경로를 작성합니다.

text

/
├─ package.json
├─ src/
├─ docs/        <--------------- `documentRootPath` ('/docs')
│  ├─ .vitepress/
│  ├─ another-directory/
│  ├─ hello.md
│  └─ index.md
└─ ...

위와 같은 구조의 프로젝트인 경우 아래와 같이 설정해야 합니다:

javascript

// `.vitepress/config.js`
import { withSidebar } from 'vitepress-sidebar';

const vitePressOptions = {};

const vitePressSidebarOptions = {
  documentRootPath: '/docs'
};

export default defineConfig(withSidebar(vitePressOptions, vitePressSidebarOptions));

사이드바 결과가 어떻게 출력되는지 테스트하려면 debugPrint 옵션을 true로 설정하여 VitePress를 빌드해 보세요. 콘솔에 출력이 표시될 것입니다.

VitePress Sidebar의 설정에 대한 자세한 내용은 아래 옵션 섹션을 참조하세요.

설정 파일

옵션을 반드시 인자로 전달해야 하는 것은 아닙니다. 문서 옆에 sidebar.config.json 파일을 두면 자동으로 인식되며, 파일이 위치한 폴더와 그 하위의 모든 폴더에 적용됩니다. 따라서 문서의 영역별로 서로 다른 규칙을 정의할 수 있습니다.

json

// docs/sidebar.config.json
{
  "collapsed": true,
  "capitalizeFirst": true,
  "useTitleFromFileHeading": true
}

위와 같이 파일을 두면 VitePress 설정은 다음으로 충분합니다:

javascript

// docs/.vitepress/config.mjs
import { defineConfig } from 'vitepress';
import { withSidebar } from 'vitepress-sidebar';

export default defineConfig(withSidebar({ title: 'My Docs' }));

자세한 내용은 설정 파일 페이지를 참고하세요.

코드 예시

javascript

import { withSidebar } from 'vitepress-sidebar';

const vitePressConfigs = {
  title: 'VitePress Sidebar',
  themeConfig: {
    // ...
  }
};

export default defineConfig(
  withSidebar(vitePressConfigs, {
    /*
     * 자세한 지침은 아래 링크를 참조하세요:
     * https://vitepress-sidebar.cdget.com/guide/options
     */
    //
    // ============ [ RESOLVING PATHS ] ============
    // documentRootPath: '/',
    // scanStartPath: null,
    // resolvePath: null,
    // basePath: null,
    // followSymlinks: false,
    //
    // ============ [ GROUPING ] ============
    // collapsed: false,
    // collapseDepth: 2,
    // collapseFromLevel: 1,
    // rootGroupText: 'Contents',
    // rootGroupLink: 'https://github.com/jooy2',
    // rootGroupCollapsed: false,
    //
    // ============ [ GETTING MENU TITLE ] ============
    // useTitleFromFileHeading: false,
    // useTitleFromFrontmatter: false,
    // useFolderTitleFromIndexFile: false,
    // frontmatterTitleFieldName: 'title',
    // dynamicRouteTitleParam: 'title',
    //
    // ============ [ GETTING MENU LINK ] ============
    // useFolderLinkFromSameNameSubFile: false,
    // useFolderLinkFromIndexFile: false,
    // folderLinkNotIncludesFileName: false,
    //
    // ============ [ INCLUDE / EXCLUDE ] ============
    // excludeByGlobPattern: ['README.md', 'folder/'],
    // excludeFilesByFrontmatterFieldName: 'exclude',
    // excludeByFolderDepth: undefined,
    // includeDotFiles: false,
    // includeEmptyFolder: false,
    // includeRootIndexFile: false,
    // includeFolderIndexFile: false,
    // includeDynamicRoutes: false,
    //
    // ============ [ STYLING MENU TITLE ] ============
    // hyphenToSpace: false,
    // underscoreToSpace: false,
    // capitalizeFirst: false,
    // capitalizeEachWords: false,
    // keepMarkdownSyntaxFromTitle: false,
    // removePrefixAfterOrdering: false,
    // prefixSeparator: '.',
    //
    // ============ [ SORTING ] ============
    // manualSortFileNameByPriority: ['first.md', 'second', 'third.md'],
    // sortFolderTo: null,
    // sortMenusByName: false,
    // sortMenusByFileDatePrefix: false,
    // sortMenusByFrontmatterOrder: false,
    // frontmatterOrderDefaultValue: 0,
    // sortMenusByFileCreateDate: false,
    // sortMenusByFileModifyDate: false,
    // sortMenusByFrontmatterDate: false,
    // sortMenusOrderByDescending: false,
    // sortMenusOrderNumericallyFromTitle: false,
    // sortMenusOrderNumericallyFromLink: false,
    // sortMenusByCustomFunction: (a, b) => a.fileName.localeCompare(b.fileName),
    //
    // ============ [ MISC ] ============
    // debugPrint: false,
  })
);

출력 예시

text

{
  documentRootPath: 'javascript',
  useTitleFromFileHeading: true,
  hyphenToSpace: true,
  excludeByGlobPattern: ['vitepress-how-to']
}

/*
[
  {
    text: 'examples',
    items: [
      {
        text: 'Examples',
        link: '/javascript/examples/examples'
      }
    ]
  },
  {
    text: 'functions',
    items: [
      {
        text: 'prototypes',
        items: [
          {
            text: 'Array',
            items: [
              {
                text: 'Array.indexOf',
                link: '/javascript/functions/prototypes/Array/Array.indexOf'
              }
            ]
          }
        ]
      }
    ]
  },
  {
    text: 'Getting Started',
    link: '/javascript/getting_started'
  }
];
*/

시작하기 ​

설치 ​

동작 과정 ​

사용 방법 ​

1. withSidebar 사용 (권장) ​

2. generateSidebar 사용 ​

설정 파일 ​

코드 예시 ​

출력 예시 ​

시작하기

설치

동작 과정

사용 방법

1. `withSidebar` 사용 (권장)

2. `generateSidebar` 사용

설정 파일

코드 예시

출력 예시