mdbook-toc

프로그램 소개

mdbook-toc은 mdbook 빌드 과정에 포함되어 문서 본문 내의 특정 위치에 인라인 목차를 자동으로 생성하는 전처리기입니다. 기본 마커를 인식하고 해당 마커 이후의 챕터에 포함된 헤딩(Heading)을 기반으로 구조화된 목차를 만듭니다.

주요 기능

• 인라인 목차 마커 인식 및 치환: 기본 마커인 <!– toc –>를 기준으로 동작하여, 마커가 위치한 챕터의 헤딩을 분석하고 인라인 목차를 자동으로 생성합니다.
• 마커 문자열 커스터마이징: GitLab 스타일의 [[_TOC_]]나 GitHub 스타일 같은 다른 표기를 사용할 수 있습니다. book.toml의 marker 옵션을 설정하여 원하는 마커 문자열을 지정할 수 있으며, 여러 줄로 구성된 마커도 지원합니다.
• 목차에 포함할 헤딩 레벨 지정: 기본적으로 목차는 헤딩 레벨 4(####)까지 포함하지만, max-level 옵션을 book.toml에 지정하여 포함할 최대 헤딩 깊이를 자유롭게 조정할 수 있습니다.

설치 및 시작

다음 단계를 따라 mdbook-toc을 설치하고 프로젝트에 적용할 수 있습니다.

1. 도구 설치: 터미널에서 다음 명령어를 사용하여 mdbook-toc을 설치합니다.
   cargo install mdbook-toc
2. 전처리기 설정: book.toml 파일에 다음 설정을 추가하여 mdbook-toc을 전처리기로 등록합니다.
   [preprocessor.toc]
command = "mdbook-toc"
renderer = ["html"]
3. 문서 작성: 목차를 삽입하고 싶은 markdown 문서의 원하는 위치에 마커를 입력합니다.
   <!-- toc -->

설정을 마친 후 기존처럼 mdbook 명령어를 사용하여 문서를 빌드하면 해당 위치에 목차가 자동으로 포함됩니다.

활용 예시

• 마커 옵션을 변경하여 GitLab 스타일의 목차 표기([[ _TOC_ ]])를 사용할 수 있습니다.
• 긴 문서에서 목차의 깊이가 너무 깊어지는 것을 방지하기 위해 max-level 옵션을 활용할 수 있습니다.
• 기본 헤딩 마커 외에도 별도의 형식을 사용자 정의하여 프로젝트의 스타일 가이드에 맞출 수 있습니다.