메인 컨텐츠로 이동
버전: 2.0.0-beta.21

제목과 목차

마크다운 제목 단락

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

## 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값을 추가할 수 있습니다.

ID 충돌 피하기

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

인라인 목차

마크다운 문서는 화면 오른쪽 상단에 목차를 보여줍니다. 하지만 MDX 덕분에 마크다운 문서 내에 바로 목차 단락을 추가하는 기능도 사용할 수 있습니다.

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

import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} />

전역으로 설정한 toc는 제목 아이템 목록을 가리킵니다.

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}
/>

사용자 지정 목차 생성

목차는 Remark 플러그인으로 마크다운 소스를 구문 분석해 만들어집니다. 이 과정에서 가긍정적이고 가부정적인 예외 사례가 만들어집니다.

숨길 수 있는 영역 내의 마크다운 제목은 여전히 목차에 표시됩니다. 예를 들어 Tabsdetails 내의 제목은 제외되지 않습니다.

마크다운이 아닌 제목은 목차에 표시되지 않습니다. 이런 동작은 앞에서 언급한 문제를 해결하는데 유리하게 활용할 수 있습니다.

<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>

좀 더 자연스럽게 추가 제목을 삽입하거나 특정 제목을 무시하는 기능은 현재 작업중입니다. 이 기능이 중요한 경우 여러분이 어떻게 사용하고 있는지 알려주세요.


주의

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

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