Skip to main content
Version: 3.5.1

标题和目录

¥Headings and Table of contents

Markdown 标题​

¥Markdown headings

你可以使用常规 Markdown 标题。

¥You can use regular Markdown headings.

## Level 2 title

### Level 3 title

#### Level 4 title

每个 Markdown 标题将显示为目录条目。

¥Each Markdown heading will appear as a table of contents entry.

标题 ID​

¥Heading IDs

每个标题都有一个可以自动生成或显式指定的 ID。标题 ID 允许你链接到 Markdown 或 JSX 中的特定文档标题：

¥Each heading has an ID that can be automatically generated or explicitly specified. Heading IDs allow you to link to a specific document heading in Markdown or JSX:

[link](#heading-id)
<Link to="#heading-id">link</Link>

默认情况下，Docusaurus 将根据标题文本为你生成标题 ID。例如，### Hello World 将具有 ID hello-world。

¥By default, Docusaurus will generate heading IDs for you, based on the heading text. For example, ### Hello World will have ID hello-world.

生成的 ID 有一些限制：

¥Generated IDs have some limitations:

  • ID 可能不太好看

    ¥The ID might not look good

  • 你可能想要更改或翻译文本而不更新现有 ID

    ¥You might want to change or translate the text without updating the existing ID

特殊的 Markdown 语法允许你设置显式标题 id：

¥A special Markdown syntax lets you set an explicit heading id:

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

使用 write-heading-ids CLI 命令向所有 Markdown 文档添加显式 ID。

¥Use the write-heading-ids CLI command to add explicit IDs to all your Markdown documents.

避免 ID 冲突

生成的标题 ID 在每个页面上将保证是唯一的，但如果你使用自定义 ID，请确保每个 ID 在每个页面上只出现一次，否则将出现两个具有相同 ID 的 DOM 元素，这是无效的 HTML 语义，并且 将导致一个标题无法链接。

¥Generated heading IDs will be guaranteed to be unique on each page, but if you use custom IDs, make sure each one appears exactly once on each page, or there will be two DOM elements with the same ID, which is invalid HTML semantics, and will lead to one heading being unlinkable.

目录标题级别​

¥Table of contents heading level

每个 Markdown 文档的右上角都会显示一个目录。默认情况下，此表仅显示 h2 和 h3 标题，这足以概述页面结构。如果你需要更改显示的标题范围，你可以自定义最小和最大标题级别 - 每页或全局。

¥Each Markdown document displays a table of contents on the top-right corner. By default, this table only shows h2 and h3 headings, which should be sufficient for an overview of the page structure. In case you need to change the range of headings displayed, you can customize the minimum and maximum heading level — either per page or globally.

要设置特定页面的标题级别，请使用 toc_min_heading_level 和 toc_max_heading_level 标题。

¥To set the heading level for a particular page, use the toc_min_heading_level and toc_max_heading_level front matter.

myDoc.md
---
# Display h2 to h5 headings
toc_min_heading_level: 2
toc_max_heading_level: 5
---

要设置所有页面的标题级别，请使用 themeConfig.tableOfContents 选项。

¥To set the heading level for all pages, use the themeConfig.tableOfContents option.

docusaurus.config.js
export default {
  themeConfig: {
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
  },
};

如果你已全局设置选项，你仍然可以通过 front Matter 在本地覆盖它们。

¥If you've set the options globally, you can still override them locally via front matter.

注意

themeConfig 选项将适用于网站上的所有目录，包括 内联目录，但 Front Matter 选项仅影响右上角的目录。你需要使用 minHeadingLevel 和 maxHeadingLevel 属性来自定义每个 <TOCInline /> 组件。

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

内联目录​

¥Inline table of contents

借助 MDX，还可以直接在 Markdown 文档中显示内联目录。

¥It is also possible to display an inline table of contents directly inside a Markdown document, thanks to MDX.

toc 变量在任何 MDX 文档中都可用，并且包含 MDX 文档的所有标题。默认情况下，目录中仅显示 h2 和 h3 标题。你可以通过为各个 TOCInline 组件设置 minHeadingLevel 或 maxHeadingLevel 来更改可见的标题级别。

¥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} />
http://localhost:3000

toc 全局只是标题项的列表：

¥The toc global is just a list of heading items:

declare const toc: {
  value: string;
  id: string;
  level: number;
}[];

请注意，toc 全局是一个扁平数组，因此你可以轻松删除不需要的节点或插入额外的节点，并创建新的 TOC 树。

¥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}
/>
http://localhost:3000

自定义目录生成​

¥Customizing table of contents generation

目录是通过使用 Remark 插件 解析 Markdown 源代码生成的。在一些已知的边缘情况下，它会产生误报和漏报。

¥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 标题仍会显示在目录中。例如，Tabs 和 details 内的标题将不会被排除。

¥Markdown headings within hideable areas will still show up in the TOC. For example, headings within Tabs and details will not be excluded.

非 Markdown 标题不会显示在目录中。这可以帮助你解决上述问题。

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

警告

下面只是一些虚拟内容，以便在当前页面上提供更多目录项。

¥Below is just some dummy content to have more table of contents items available on the current page.

示例第 1 节​

¥Example Section 1

洛雷姆·伊普苏姆

¥Lorem ipsum

示例第 1 款 a​

¥Example Subsection 1 a

洛雷姆·伊普苏姆

¥Lorem ipsum

示例小节 1 a I​

¥Example subsubsection 1 a I

示例小节 1 a II​

¥Example subsubsection 1 a II

示例小节 1 a III​

¥Example subsubsection 1 a III

示例第 1 b 款​

¥Example Subsection 1 b

洛雷姆·伊普苏姆

¥Lorem ipsum

示例小节 1 b I​

¥Example subsubsection 1 b I

示例小节 1 b II​

¥Example subsubsection 1 b II

示例小节 1 b III​

¥Example subsubsection 1 b III

示例第 1 c 款​

¥Example Subsection 1 c

洛雷姆·伊普苏姆

¥Lorem ipsum

示例小节 1 c I​

¥Example subsubsection 1 c I

示例小节 1 c II​

¥Example subsubsection 1 c II

示例小节 1 c III​

¥Example subsubsection 1 c III

示例第 2 节​

¥Example Section 2

洛雷姆·伊普苏姆

¥Lorem ipsum

示例第 2 a 款​

¥Example Subsection 2 a

洛雷姆·伊普苏姆

¥Lorem ipsum

示例小节 2 a I​

¥Example subsubsection 2 a I

示例小节 2 a II​

¥Example subsubsection 2 a II

示例小节 2 a III​

¥Example subsubsection 2 a III

示例第 2 b 款​

¥Example Subsection 2 b

洛雷姆·伊普苏姆

¥Lorem ipsum

示例小节 2 b I​

¥Example subsubsection 2 b I

示例小节 2 b II​

¥Example subsubsection 2 b II

示例小节 2 b III​

¥Example subsubsection 2 b III

示例第 2 c 款​

¥Example Subsection 2 c

洛雷姆·伊普苏姆

¥Lorem ipsum

示例小节 2 c I​

¥Example subsubsection 2 c I

示例小节 2 c II​

¥Example subsubsection 2 c II

示例小节 2 c III​

¥Example subsubsection 2 c III

示例第 3 节​

¥Example Section 3

洛雷姆·伊普苏姆

¥Lorem ipsum

第 3 节 a 示例​

¥Example Subsection 3 a

洛雷姆·伊普苏姆

¥Lorem ipsum

示例小节 3 a I​

¥Example subsubsection 3 a I

示例小节 3 a II​

¥Example subsubsection 3 a II

示例小节 3 a III​

¥Example subsubsection 3 a III

示例第 3 b 款​

¥Example Subsection 3 b

洛雷姆·伊普苏姆

¥Lorem ipsum

示例小节 3 b I​

¥Example subsubsection 3 b I

示例小节 3 b II​

¥Example subsubsection 3 b II

示例小节 3 b III​

¥Example subsubsection 3 b III

示例第 3 c 款​

¥Example Subsection 3 c

洛雷姆·伊普苏姆

¥Lorem ipsum

示例小节 3 c I​

¥Example subsubsection 3 c I

示例小节 3 c II​

¥Example subsubsection 3 c II

示例小节 3 c III​

¥Example subsubsection 3 c III