메인 컨텐츠로 이동
버전: Canary 🚧

제목과 목차

마크다운 제목 단락​

마크다운에서 일반적으로 제목 단락을 만드는 방법을 사용할 수 있습니다.

## Level 2 title

### Level 3 title

#### Level 4 title

각 마크다운 제목 단락은 목차에 표시됩니다.

제목 단락 ID​

각 제목 단락은 자동으로 생성되거나 별도 지정한 ID 값을 가집니다. 제목 단락 ID는 마크다운이나 JSX에서 해당 문서에 대한 링크를 작성할 때 사용할 수 있습니다.

[link](#heading-id)
<Link to="#heading-id">link</Link>

기본적으로 도큐사우루스에서는 제목 단락 텍스트에 따라 ID를 자동으로 생성합니다. 예를 들어 ### Hello World라고 작성한 제목 단락은 hello-world를 ID값으로 가집니다.

자동으로 생성된 ID는 약간의 제약이 있습니다.

  • ID가 직관적이지 않을 수 있습니다.
  • 기존에 생성된 ID는 바꾸지 않고 텍스트만 변경하거나 번역해야 하는 상황도 있습니다.

특별한 마크다운 구문은 제목 단락 id 설정을 지원합니다.

### Hello World {#my-explicit-id}
팁

write-heading-ids CLI 명령을 사용하면 모든 마크다운 문서에 ID값을 추가할 수 있습니다.

Avoid colliding IDs

생성된 제목 단락 ID는 각 페이지에서는 고유한 것이 보장되지만 사용자 지정 ID를 사용하는 경우에는 각 ID가 각 페이지에서 정확하게 한 번만 표시되는지 확인하세요. 그렇지 않으면 같은 ID를 가진 두 개의 DOM 요소가 존재하게 됩니다. 이는 잘못된 HTML이며 제목과 적절하게 연결할 수 없게 됩니다.

목차 제목 수준​

마크다운 문서는 화면 오른쪽 상단에 목차를 보여줍니다. 기본적으로 목차에서는 h2, h3 제목만 표시하므로 페이지 구조를 한 눈에 보기에 충분합니다. 표시되는 제목 범위를 수정하고자 한다면 페이지 단위 또는 전역적으로 최소, 최대 제목 수준을 지정할 수 있습니다.

특정 페이지의 제목 수준을 설정하려면 프런트매터에서 toc_min_heading_level와 toc_max_heading_level 항목을 설정합니다.

myDoc.md
---
# h2부터 h5까지 제목을 표시합니다
toc_min_heading_level: 2
toc_max_heading_level: 5
---

모든 페이지의 제목 수준을 설정하려면 themeConfig.tableOfContents 옵션을 사용합니다.

docusaurus.config.js
export default {
  themeConfig: {
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
  },
};

옵션을 전역적으로 설정했더라도 프런트매터에서 다시 재정의할 수 있습니다.

참고

themeConfig 옵션은 인라인 목차를 포함한 사이트 전체 목차에 적용되지만 프런트매터 옵션은 오른쪽 상단 목차에만 영향을 미칩니다. 각 <TOCInline /> 컴포넌트를 사용자 지정하기 위해서는 minHeadingLevel과 maxHeadingLevel 속성을 사용해야 합니다.

인라인 목차​

MDX 덕분에 마크다운 문서 내에 바로 목차 단락을 추가하는 기능도 사용할 수 있습니다.

MDX 문서 내에서 toc 변수를 사용할 수 있습니다. 현재 MDX 문서의 모든 제목 단락을 포함합니다. 기본적으로는 h2와 h3 제목 단락만 목차에 표시됩니다. minHeadingLevel 또는 maxHeadingLevel 설정에서 각 TOCInline 컴포넌트를 위해 표시할 제목 수준을 변경할 수 있습니다.

import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} />
http://localhost:3000

The toc global is just a list of heading items:

declare const toc: {
  value: string;
  id: string;
  level: number;
}[];

toc global은 1차원 배열이라서 원하지 않는 노드를 쉽게 잘라낼 수 있고 추가 노드를 삽입하거나 새로운 목차 트리를 만들 수 있습니다.

import TOCInline from '@theme/TOCInline';

<TOCInline
  // h2와 h4 제목만 표시합니다.
  toc={toc.filter((node) => node.level === 2 || node.level === 4)}
  minHeadingLevel={2}
  // 기본 h2, h3 제목에 추가해 h4 제목을 표시합니다.
  maxHeadingLevel={4}
/>
http://localhost:3000

사용자 지정 목차 생성​

The table-of-contents is generated by parsing the Markdown source with a Remark plugin. There are known edge-cases where it generates false-positives and false-negatives.

Markdown headings within hideable areas will still show up in the TOC. For example, headings within Tabs and details will not be excluded.

Non-Markdown headings will not show up in the TOC. This can be used to your advantage to tackle the aforementioned issue.

<details>
<summary>Some details containing headings</summary>
<h2 id="#heading-id">I'm a heading that will not show up in the TOC</h2>

Some content...

</details>

The ability to ergonomically insert extra headings or ignore certain headings is a work-in-progress. If this feature is important to you, please report your use-case in this issue.

warning

아래는 현재 페이지에서 더 많은 목차 항목을 사용할 수 있는 더미 콘텐츠입니다.

Example Section 1​

Lorem ipsum

Example Subsection 1 a​

Lorem ipsum

Example subsubsection 1 a I​

Example subsubsection 1 a II​

Example subsubsection 1 a III​

Example Subsection 1 b​

Lorem ipsum

Example subsubsection 1 b I​

Example subsubsection 1 b II​

Example subsubsection 1 b III​

Example Subsection 1 c​

Lorem ipsum

Example subsubsection 1 c I​

Example subsubsection 1 c II​

Example subsubsection 1 c III​

Example Section 2​

Lorem ipsum

Example Subsection 2 a​

Lorem ipsum

Example subsubsection 2 a I​

Example subsubsection 2 a II​

Example subsubsection 2 a III​

Example Subsection 2 b​

Lorem ipsum

Example subsubsection 2 b I​

Example subsubsection 2 b I​

Example subsubsection 2 b III​

Example Subsection 2 c​

Lorem ipsum

Example subsubsection 2 c I​

Example subsubsection 2 c II​

Example subsubsection 2 c III​

Example Section 3​

Lorem ipsum

Example Subsection 3 a​

Lorem ipsum

Example subsubsection 3 a I​

Example subsubsection 3 a II​

Example subsubsection 3 a III​

Example Subsection 3 b​

Lorem ipsum

Example subsubsection 3 b I​

Example subsubsection 3 b II​

Example subsubsection 3 b III​

Example Subsection 3 c​

Lorem ipsum

Example subsubsection 3 c I​

Example subsubsection 3 c II​

Example subsubsection 3 c III​