标题和目录
Markdown 标题
您可以使用常规的 Markdown 标题。
## Level 2 title
### Level 3 title
#### Level 4 title
每个 Markdown 标题将作为目录条目出现。
标题 IDs
每个标题都有一个可以自动生成或显式指定的 ID。标题 id 允许您链接到 Markdown 或 JSX 中的特定文档标题:
[link](#heading-id)
<Link to="#heading-id">link</Link>
默认情况下，Docusaurus 将根据标题文本为您生成标题 id。例如，### Hello World的 ID 为Hello - World。
生成的 id 有一些限制:
- ID 可能看起来不太好
- 您可能希望在不更新现有 ID 的情况下更改或翻译文本
一个特殊的 Markdown 语法可以让你设置一个显式的标题 id:
### Hello World {#my-explicit-id}
使用**write-heading-ids** CLI 命令为所有 Markdown 文档添加显式 id。
生成的标题 ID 将保证在每个页面上是唯一的，但如果使用自定义 ID，请确保每个标题在每个页面上只出现一次，否则将有两个具有相同 ID 的 DOM 元素，这是无效的 HTML 语义，并将导致一个标题不可链接。
目录标题级别
每个 Markdown 文档在右上角显示一个目录。默认情况下，该表只显示 h2 和 h3 标题，这应该足以概述页面结构。如果您需要更改显示的标题范围，您可以自定义最小和最大标题级别-每个页面或全局。
To set the heading level for a particular page, use the toc_min_heading_level and toc_max_heading_level front matter.
---
# Display h2 to h5 headings
toc_min_heading_level: 2
toc_max_heading_level: 5
---
To set the heading level for all pages, use the themeConfig.tableOfContents option.
module.exports = {
themeConfig: {
tableOfContents: {
minHeadingLevel: 2,
maxHeadingLevel: 5,
},
},
};
If you've set the options globally, you can still override them locally via front matter.
The themeConfig option would apply to all TOC on the site, including inline TOC, but front matter options only affect the top-right TOC. You need to use the minHeadingLevel and maxHeadingLevel props to customize each <TOCInline /> component.
内联目录
It is also possible to display an inline table of contents directly inside a Markdown document, thanks to MDX.
The toc variable is available in any MDX document and contains all the headings of an MDX document. By default, only h2 and h3 headings are displayed in the TOC. You can change which heading levels are visible by setting minHeadingLevel or maxHeadingLevel for individual TOCInline components.
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;
}[];
Note that the toc global is a flat array, so you can easily cut out unwanted nodes or insert extra nodes, and create a new TOC tree.
import TOCInline from '@theme/TOCInline';
<TOCInline
// Only show h2 and h4 headings
toc={toc.filter((node) => node.level === 2 || node.level === 4)}
minHeadingLevel={2}
// Show h4 headings in addition to the default h2 and h3 headings
maxHeadingLevel={4}
/>
自定义目录生成
目录表是通过使用Remark plugin解析 Markdown 源代码生成的。在已知的边缘情况下，它会产生假阳性和假阴性。
可隐藏区域内的 Markdown 标题仍然会显示在 TOC 中。例如，Tabs和details中的标题将不会被排除。
非 Markdown 标题将不会显示在 TOC 中。这可以成为你解决上述问题的优势。
<details>
<summary>一些包含标题的细节</summary>
<h2 id="#heading-id">我是一个不会出现在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 II
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