跳到主要内容
版本：3.0.0-rc.1

标题和目录

Markdown headings​

你可以用常规的 Markdown 标题。

## 二级标题

### 三级标题

### 四级标题

每个 Markdown 标题都会变成目录里的一条内容。

Heading IDs​

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

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

默认情况下，Docusaurus 会根据标题文本为你生成标题 ID。 For example, ### Hello World will have ID hello-world.

Generated IDs have some limitations:

  • ID 可能看起来不好看
  • You might want to change or translate the text without updating the existing ID

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

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

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

Avoid colliding IDs

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

Table of contents heading level​

每个 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.

myDoc.md
---
# 显示 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.

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

如果已经设置了全局选项，你仍然可以通过前言局部覆盖这些设置。

备注

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 文档中显示一个内联目录。

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

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

Customizing table of contents generation​

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

注意

下面只是一些随便写的内容，让本页的目录示例看起来更充实一点。

Example Section 1​

Lorem ipsum

Example Subsection 1 a​

Lorem ipsum

示例小节 1 a I​

示例小节 1 a II​

示例小节 1 a III​

Example Subsection 1 b​

Lorem ipsum

示例小节 1 b I​

示例小节 1 b II​

示例小节 1 b III​

Example Subsection 1 c​

Lorem ipsum

示例小节 1 c I​

示例小节 1 c II​

示例小节 1 c III​

Example Section 2​

Lorem ipsum

Example Subsection 2 a​

Lorem ipsum

示例小节 2 a I​

示例小节 2 a II​

示例小节 2 a III​

Example Subsection 2 b​

Lorem ipsum

示例小节 2 b I​

示例小节 2 b II​

示例小节 2 b III​

Example Subsection 2 c​

Lorem ipsum

示例小节 2 c I​

示例小节 2 c II​

示例小节 2 c III​

Example Section 3​

Lorem ipsum

Example Subsection 3 a​

Lorem ipsum

示例小节 3 a I​

示例小节 3 a II​

示例小节 3 a III​

Example Subsection 3 b​

Lorem ipsum

示例小节 3 b I​

示例小节 3 b II​

示例小节 3 b III​

Example Subsection 3 c​

Lorem ipsum

示例小节 3 c I​

示例小节 3 c II​

示例小节 3 c III​