메인 컨텐츠로 이동
버전: 불안정 🚧

제목과 목차

마크다운 제목 단락​

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

## 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가 직관적이지 않을 수 있습니다.
  • You might want to change or translate the text without updating the existing ID to avoid breaking links

A special syntax lets you set an explicit heading id.

### Hello World {/* #my-explicit-id */}

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

The heading id comment must start with #, be placed at the end of the heading and will be stripped from the rendered output.

Legacy {#id} syntax for MDX files

For MDX files, the {#id} syntax should be avoided. Since Docusaurus v3 and MDX v2, it is not valid MDX syntax anymore. It can break external tools that support MDX (IDEs and linters). It is only supported in Docusaurus for backward compatibility, thanks to the markdown.mdx1Compat.headingIds config option. The comment-based syntax should be preferred for MDX documents.

팁

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.

경고

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

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​