进阶 docusaurus.io 2026-10-13 10:58:59 · 29 阅读
第12章 Docusaurus Markdown 特性详解
版本：2.x Markdown 特性
文档是你产品面向用户的重要界面之一。一份撰写精良、组织有序的文档能帮助用户快速理解产品。我们的共同目标是让用户尽可能高效地找到并理解所需信息。
Docusaurus 2 利用现代工具帮你轻松编写交互式文档。你可以嵌入 React 组件，或者构建实时代码块，让用户当场操作代码。开始分享你的灵光乍现时刻，用那些令人难以离开的代码吸引潜在用户。这可能是吸引新用户最有效的方式。
提示：本节假设你使用的是官方 Docusaurus 内容插件。
标准特性
Markdown 是一种语法，能让你用易读的格式编写格式化内容。
我们使用 MDX 作为解析引擎，它的功能远不止解析标准 Markdown 语法，还可以在文档中渲染 React 组件。
### 我的文档章节
你好世界消息，其中包含 粗体 文本、_斜体_ 文本以及 [链接](/)
http://localhost:3000 我的文档章节 你好世界消息，其中包含粗体文本、斜体文本和链接 Markdown 是声明式的 有些人可能认为 Markdown 和 HTML 之间存在一一对应关系，例如  总是会变成
，原样输出。但事实并非如此。Markdown 语法  只是声明式地告知 Docusaurus 此处需要插入一张图片，但我们可能执行其他操作，例如将文件路径转换为 URL 路径，因此生成的标记可能与其他 Markdown 渲染器的输出不同，也与直接手动转换为等价 JSX/HTML 代码的结果不同。总体而言，你只需假设标记的语义（例如 ``` 围栏变成代码块，> 变成引用等），而不必假设实际的编译输出。
Front matter
Front matter 用于向 Markdown 文件添加元数据。所有内容插件都有自己的 front matter 模式，并据此丰富从内容或其他配置中推断出的默认元数据。
Front matter 位于文件顶部，用三个破折号 --- 包裹。内容会被解析为 YAML。
---
title: 我的文档标题
more_data:
- 可以是内容
- 格式: 对象
或: 数组
---
引用 Markdown 引用块的样式很美观： > Easy to maintain open source documentation websites.
>
> — Docusaurus
http://localhost:3000 Easy to maintain open source documentation websites. — Docusaurus 折叠块 Markdown 可以嵌入 HTML 元素，其中 details 元素的样式也很美观： ### Details element example
http://localhost:3000Details element exampleToggle me!This is the detailed content
Nested toggle! Some surprise inside...😲😲😲😲😲 note实际上，这些并不是真正的 HTML 元素，而是 React JSX 元素，我们接下来会讲到！
你好世界消息，其中包含 粗体 文本、_斜体_ 文本以及 [链接](/)
http://localhost:3000 我的文档章节 你好世界消息，其中包含粗体文本、斜体文本和链接 Markdown 是声明式的 有些人可能认为 Markdown 和 HTML 之间存在一一对应关系，例如  总是会变成
，原样输出。但事实并非如此。Markdown 语法  只是声明式地告知 Docusaurus 此处需要插入一张图片，但我们可能执行其他操作，例如将文件路径转换为 URL 路径，因此生成的标记可能与其他 Markdown 渲染器的输出不同，也与直接手动转换为等价 JSX/HTML 代码的结果不同。总体而言，你只需假设标记的语义（例如 ``` 围栏变成代码块，> 变成引用等），而不必假设实际的编译输出。
Front matter
Front matter 用于向 Markdown 文件添加元数据。所有内容插件都有自己的 front matter 模式，并据此丰富从内容或其他配置中推断出的默认元数据。
Front matter 位于文件顶部，用三个破折号 --- 包裹。内容会被解析为 YAML。
---title: 我的文档标题
more_data:
- 可以是内容
- 格式: 对象
或: 数组
---
引用 Markdown 引用块的样式很美观： > Easy to maintain open source documentation websites.
>
> — Docusaurus
http://localhost:3000 Easy to maintain open source documentation websites. — Docusaurus 折叠块 Markdown 可以嵌入 HTML 元素，其中 details 元素的样式也很美观： ### Details element example
点我展开！
这是折叠的内容
嵌套折叠！里面还有惊喜……
😲😲😲😲😲
http://localhost:3000Details element exampleToggle me!This is the detailed content
Nested toggle! Some surprise inside...😲😲😲😲😲 note实际上，这些并不是真正的 HTML 元素，而是 React JSX 元素，我们接下来会讲到！
