跳到主要内容

标题和目录

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}
提示

使用 write-heading-ids CLI 命令，可以为你的所有 Markdown 文档批量添加明确的 ID。

避免 ID 冲突

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

目录的标题级别​

每个 Markdown 文档的右上角都会显示一个目录。默认情况下，这个目录只显示 h2 和 h3 级别的标题，这对于概览页面结构来说应该足够了。如果你需要更改显示的标题范围，你可以为单个页面或全局自定义最小和最大的标题级别。

要为特定页面设置标题级别，请使用 toc_min_heading_level 和 toc_max_heading_level 头部元数据。

myDoc.md
---
# 显示 h2 到 h5 级别的标题
toc_min_heading_level: 2
toc_max_heading_level: 5
---

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

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

如果你已经全局设置了这些选项，仍然可以通过头部元数据在局部进行覆盖。

备注

themeConfig 选项将应用于网站上的所有目录（TOC），包括行内目录；但头部元数据选项只影响右上角的目录。你需要使用 minHeadingLevel 和 maxHeadingLevel 属性(props) 来定制每个 <TOCInline /> 组件。

行内目录​

借助 MDX，你也可以在 Markdown 文档内部直接显示一个行内目录。

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

import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} />
http://localhost:3000

toc 全局变量只是一个标题项目的列表：

declare const toc: {
  value: string; // 标题的文本内容
  id: string; // 标题的 ID
  level: number; // 标题的级别 (例如 h2, h3)
}[];

请注意，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}
/>
http://localhost:3000

自定义目录生成​

目录是通过一个 Remark 插件解析 Markdown 源文件来生成的。在某些已知的边缘情况下，它可能会产生误报（false-positives）和漏报（false-negatives）。

可隐藏区域内的 Markdown 标题仍然会出现在目录中。例如，<Tabs> 和 <details> 内部的标题不会被排除。

非 Markdown 标题则不会出现在目录中。你可以利用这一点来解决上述问题。

<details>
<summary>包含标题的一些详情</summary>
<h2 id="#heading-id">我是一个不会出现在目录中的标题</h2>

一些内容...

</details>

便捷地插入额外标题或忽略某些标题的功能仍在开发中。如果这个功能对你很重要，请在这个 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

示例子小节 3 c I​

示例子小节 3 c II​

示例子小节 3 c III​