标题和目录
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