跳到主要内容

标题和目录

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 在每个页面上只出现一次，否则将有两个具有相同 ID 的 DOM 元素，这属于无效的 HTML 语义，并将导致一个标题无法链接。

目录标题级别​

每个 Markdown 文档都在右上角显示一个目录。默认情况下，此目录仅显示 h2 和 h3 标题，这对于页面结构的概述应该足够了。如果您需要更改显示的标题范围，您可以自定义最小和最大标题级别——可以针对每个页面或全局设置。

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

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,
    },
  },
};

如果您已全局设置选项，您仍然可以通过前端 matter 在本地覆盖它们。

备注

themeConfig 选项将应用于网站上的所有 TOC，包括 内联 TOC ，但前端 matter 选项仅影响右上角的 TOC。您需要使用 minHeadingLevel 和 maxHeadingLevel 属性来自定义每个 <TOCInline /> 组件。

内联目录​

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

toc 变量可在任何 MDX 文档中使用，并包含 MDX 文档的所有标题。默认情况下，TOC 中仅显示 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 全局变量是一个扁平数组，因此您可以轻松剪切不需要的节点或插入额外的节点，并创建一个新的 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 标题仍将显示在 TOC 中。例如， Tabs 和 details 内的标题不会被排除。

非 Markdown 标题将不会显示在 TOC 中。这可以用来解决上述问题。

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

一些内容...

</details>

轻松插入额外标题或忽略某些标题的功能正在开发中。如果此功能对您很重要，请在此 问题 中报告您的用例。

注意

以下是只是一些虚拟内容，以便在本页上提供更多可用的目录项。

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

编辑此页
最后由 HomeUbuntu 于 更新