跳到主要内容

标题和目录

Markdown 标题​

您可以使用常规的 Markdown 标题。

## 二级标题

### 三级标题

#### 四级标题

每个 Markdown 标题都将作为目录条目出现。

标题 ID​

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

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

默认情况下，Docusaurus 将根据标题文本为您生成标题 ID。例如，### 你好世界 将有 ID 你好世界。

生成的 ID 有一些限制：

  • ID 可能看起来不太好
  • 您可能想要更改或翻译文本而不更新现有 ID

特殊的 Markdown 语法允许您设置明确的标题 ID：

### 你好世界 {#my-explicit-id}
提示

使用 write-heading-ids CLI 命令为所有 Markdown 文档添加明确的 ID。

避免 ID 冲突

生成的标题 ID 在每个页面上都保证是唯一的，但如果您使用自定义 ID，请确保每个 ID 在每个页面上只出现一次，否则会有两个具有相同 ID 的 DOM 元素，这是无效的 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 选项将应用于站点上的所有目录，包括内联目录，但前置元数据选项仅影响右上角的目录。您需要使用 minHeadingLevel 和 maxHeadingLevel 属性来自定义每个 <TOCInline /> 组件。

内联目录​

得益于 MDX，还可以直接在 Markdown 文档中显示内联目录。

toc 变量在任何 MDX 文档中都可用，并包含 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;
  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}
/>
http://localhost:3000

自定义目录生成​

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

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

非 Markdown 标题不会出现在目录中。这可以用来解决前面提到的问题。

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

一些内容...

</details>

以人体工程学的方式插入额外标题或忽略某些标题的能力仍在开发中。如果此功能对您很重要，请在此问题中报告您的用例。

注意

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

示例章节 1​

Lorem ipsum

示例子章节 1 a​

Lorem ipsum

示例子子章节 1 a I​

示例子子章节 1 a II​

示例子子章节 1 a III​

示例子章节 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

Example subsubsection 3 c I​

Example subsubsection 3 c II​

Example subsubsection 3 c III​