跳到主要内容

5、标题和目录

标题和目录​

Markdown 标题​

你可以使用常规 Markdown 标题。

## Level 2 title

### Level 3 title

#### Level 4 title

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

标题 ID​

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

[link](#heading-id)
<Link to="#heading-id">link</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 标题。

myDoc.md

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

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

docusaurus.config.js

export default {
  themeConfig: {
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
  },
};

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

提示

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

内联目录​

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

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

import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} />

http://localhost:3000

image-20240923220709342

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

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

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

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}
/>

image-20240923220813661

自定义目录生成​

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

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

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

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

符合人机工程学地插入额外标题或忽略某些标题的能力正在开发中。如果此功能对你很重要，请在 这个问题 中报告你的用例。

注意

警告

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

示例第 1 节​

洛雷姆·伊普苏姆

示例第 1 款 a​

洛雷姆·伊普苏姆

示例小节 1 a I​

示例小节 1 a II​

示例小节 1 a III​

示例第 1 b 款​

洛雷姆·伊普苏姆

示例小节 1 b I​

示例小节 1 b II​

示例小节 1 b III​

示例第 1 c 款​

洛雷姆·伊普苏姆

示例小节 1 c I​

示例小节 1 c II​

示例小节 1 c III​

示例第 2 节​

洛雷姆·伊普苏姆

示例第 2 a 款​

洛雷姆·伊普苏姆

示例小节 2 a I​

示例小节 2 a II​

示例小节 2 a III​

示例第 2 b 款​

洛雷姆·伊普苏姆

示例小节 2 b I​

示例小节 2 b II​

示例小节 2 b III​

示例第 2 c 款​

洛雷姆·伊普苏姆

示例小节 2 c I​

示例小节 2 c II​

示例小节 2 c III​

示例第 3 节​

洛雷姆·伊普苏姆

第 3 节 a 示例​

洛雷姆·伊普苏姆

示例小节 3 a I​

示例小节 3 a II​

示例小节 3 a III​

示例第 3 b 款​

洛雷姆·伊普苏姆

示例小节 3 b I​

示例小节 3 b II​

示例小节 3 b III​

示例第 3 c 款​

洛雷姆·伊普苏姆

示例小节 3 c I​

示例小节 3 c II​

示例小节 3 c III​

标签：
最后由 One 于 更新
0%