标题和目录
Markdown 标题
你可以用常规的 Markdown 标题。
## 二级标题
### 三级标题
### 四级标题
每个 Markdown 标题都会变成目录里的一条内容。
标题 ID
每个标题都有一个 ID，它可以自动生成，也可以被显式指定。 标题 ID 允许你在 Markdown 或 JSX 中链接到某个特定的文档标题：
[链接](#heading-id)
<Link to="#heading-id">链接</Link>
默认情况下，Docusaurus 会根据标题文本为你生成标题 ID。 比如，### Hello World 所对应的 ID 就是 hello-world。
自动生成的 ID 有一些不足：
- ID 可能看起来不好看
- 你可能想要修改或翻译文本而不改动已有的 ID
有一种特殊的 Markdown 语法，允许你设置一个显式标题 ID：
### Hello World {#my-explicit-id}
Use the write-heading-ids CLI command to add explicit IDs to all your Markdown documents.
自动生成的标题 ID 会保证 在每个页面上都是唯一的，但如果你使用了自定义 ID，请确保每个 ID 都只出现一次。否则会出现两个有相同 ID 的 DOM 元素，而这是无效的 HTML 语义，会导致一个标题无法被链接到。
目录标题级别
每个 Markdown 文档会在右上角显示一个目录栏。 目录默认只显示 h2 和 h3 标题，这些标题应该足够概述页面结构了。 如果你需要更改显示的标题范围，你可以自定义最小和最大的标题级别——既可以按页配置，也可以全局设置。
要设置某个页面的标题级别，可以使用 toc_min_heading_level 和 toc_max_heading_level 前言。
---
# 显示 h2 到 h5 标题
toc_min_heading_level: 2
toc_max_heading_level: 5
---
To set the heading level for all pages, use the themeConfig.tableOfContents option.
export default {
themeConfig: {
tableOfContents: {
minHeadingLevel: 2,
maxHeadingLevel: 5,
},
},
};
如果已经设置了全局选项，你仍然可以通过前言局部覆盖这些设置。
themeConfig 选项会作用于网站的所有目录，包括内联目录，但前言选项只会影响右上角的 TOC。 你需要用 minHeadingLevel 和 maxHeadingLevel props 来自定义每一个 <TOCInline /> 组件。
内联目录
你也可以通过 MDX，直接在 Markdown 文档中显示一个内联目录。
每个 MDX 文档都有一个 toc 变量可供使用，而它包含了此文档的所有标题。 默认情况下，目录中只显示 h2 和 h3 标题。 你可以通过设置每个 TOCInline 组件的 minHeadingLevel 或 maxHeadingLevel 来更改哪些标题级别可见。
import TOCInline from '@theme/TOCInline';
<TOCInline toc={toc} />
The toc global is just a list of heading items:
declare const toc: {
value: string;
id: string;
level: number;
}[];
要注意 toc 全局变量是一个扁平的数组，所以你可以方便地剪切不需要的节点，或者插入额外的节点，从而创建一个新的目录树。
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}
/>
自定义目录生成
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>一些包含了标题的 details</summary>
<h2 id="#heading-id">我是个标题但我不会出现在目录里</h2>
一些内容……
</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.
下面只是一些随便写的内容，让本页的目录示例看起来更充实一点。
示例章节 1
Lorem ipsum
示例段落 1 a
Lorem ipsum
示例小节 1 a I
示例小节 1 a II
示例小节 1 a III
示例段落 1 b
Lorem ipsum
示例小节 1 b I
示例小节 1 b II
示例小节 1 b III
示例段落 1 c
Lorem ipsum
示例小节 1 c I
示例小节 1 c II
示例小节 1 c III
示例章节 2
Lorem ipsum
示例段落 2 a
Lorem ipsum
示例小节 2 a I
示例小节 2 a II
示例小节 2 a III
示例段落 2 b
Lorem ipsum
示例小节 2 b I
示例小节 2 b II
示例小节 2 b III
示例段落 2 c
Lorem ipsum
示例小节 2 c I
示例小节 2 c II
示例小节 2 c III
示例章节 3
Lorem ipsum
示例段落 3 a
Lorem ipsum
示例小节 3 a I
示例小节 3 a II
示例小节 3 a III
示例段落 3 b
Lorem ipsum
示例小节 3 b I
示例小节 3 b II
示例小节 3 b III
示例段落 3 c
Lorem ipsum