Markdown 功能
道格龙（Docusaurus）使用 Markdown 作为其主要的内容创作格式。
道格龙（Docusaurus）使用现代化的工具来帮助你创建交互式文档。
MDX 编译器将 Markdown 文件转换为 React 组件，并允许你在 Markdown 内容中使用 JSX。这使你能够轻松地在内容中穿插 React 组件，创造愉悦的学习体验。
MDX playground 是你的新晋好帮手！
它是一个非常有用的调试工具，可以展示 MDX 编译器如何将 Markdown 转换为 React。
选项：请选择正确的格式（MDX 或 CommonMark）以及道格龙（Docusaurus）使用的以下插件：remark-gfm、remark-directive、rehype-raw。
MDX vs. CommonMark
道格龙（Docusaurus）使用 MDX 编译器将 .md 和 .mdx 文件都编译成 React 组件，但语法的解析方式可能会因你的设置而异。
MDX 编译器支持两种格式：
- MDX 格式：一个强大的解析器，允许使用 JSX。
- CommonMark 格式：一个符合标准的 Markdown 解析器，不允许使用 JSX。
由于历史原因，道格龙（Docusaurus） v3 默认对所有文件（包括 .md 文件）使用 MDX 格式。
你可以通过 siteConfig.markdown.format 设置或 mdx.format: md 头部元数据来选择使用 CommonMark。
如果你计划使用 CommonMark，我们推荐 siteConfig.markdown.format: 'detect' 设置。系统会根据文件扩展名自动选择合适的格式：
.md文件将使用 CommonMark 格式.mdx文件将使用 MDX 格式
CommonMark 支持目前处于实验性阶段，并且存在一些局限性。
标准功能
Markdown 是一种能让你用可读的语法编写格式化内容的语法。
### 我的文档章节
这是一条 Hello world 消息，包含一些**粗体**文本、一些_斜体_文本，以及一个[链接](/)。
Markdown 是声明式的
有些人可能认为 Markdown 和 HTML 之间存在一对一的对应关系，例如  会总是原样变成 <img src="/img/docusaurus.png" alt="预览" />。然而，事实并非如此。
Markdown 语法  只是以声明的方式告诉道格龙（Docusaurus），这里需要插入一张图片，但我们可能会做其他事情，比如将文件路径转换为 URL 路径，所以生成的标记可能与其他 Markdown 渲染器或简单地手动转写为等效 JSX/HTML 代码的输出有所不同。
头部元数据 (Front Matter)
头部元数据用于为你的 Markdown 文件添加元数据。所有的内容插件都有自己的头部元数据结构，并使用这些元数据来丰富从内容或其他配置中推断出的默认元数据。
头部元数据位于文件的最顶部，由三条短划线 --- 包围。其内容被解析为 YAML。
---
title: 我的文档标题
more_data:
- 可以作为
- as: 对象
or: 数组
---
每个官方插件的 API 文档都列出了其支持的属性：
使用 Markdown 配置中的 parseFrontMatter 函数，可以提供你自己的头部元数据解析器，或增强默认的解析器。
复用默认的解析器，并用你自己的定制逻辑来包装它，是完全可行的。这使得实现便捷的头部元数据转换、快捷方式，或与使用道格龙（Docusaurus）插件不支持的头部元数据的外部系统集成成为可能。
export default {
markdown: {
async parseFrontMatter(params) {
// params 对象包含了解析所需的所有信息，例如：
// - params.filePath: 被解析文件的路径
// - params.fileContent: 文件的原始内容
// - params.defaultParseFrontMatter: 道格龙（Docusaurus）的默认 front matter 解析函数
// 复用默认的解析器，以获取初步的解析结果
// result 对象包含：
// - result.frontMatter: 解析出的 YAML front matter 对象
// - result.content: front matter 之后的文件内容
const result = await params.defaultParseFrontMatter(params);
// 示例：处理 front matter 中 description 字段的占位符
// 这段代码会查找 description 字段中的 {{MY_VAR}} 并替换为 'MY_VALUE'
result.frontMatter.description =
result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');
// 示例：创建你自己的 front matter 快捷方式
// 如果在 front matter 中设置了 i_do_not_want_docs_pagination: true
if (result.frontMatter.i_do_not_want_docs_pagination) {
// 就自动禁用该页 面的上一页/下一页分页导航
result.frontMatter.pagination_prev = null;
result.frontMatter.pagination_next = null;
}
// 示例：重命名一个来自其他系统（如 CMS）的不支持的 front matter 字段
// 如果 front matter 中有名为 cms_seo_summary 的字段
if (result.frontMatter.cms_seo_summary) {
// 就将其值赋给道格龙（Docusaurus）支持的 description 字段
result.frontMatter.description = result.frontMatter.cms_seo_summary;
// 然后删除原来的字段，避免混淆
delete result.frontMatter.cms_seo_summary;
}
// 返回处理后的结果
return result;
},
},
};
引用
Markdown 的引用块样式精美：
> 轻松维护开源文档网站。
>
> — 道格龙（Docusaurus）
轻松维护开源文档网站。
— 道格龙（Docusaurus）
详情块
Markdown 可以嵌入 HTML 元素，而 details HTML 元素的样式也同样精美：
### Details 元素示例
<details>
<summary>点我展开！</summary>
这里是详细内容。
```js
console.log("包括代码块在内的 Markdown 功能都可用");
```
你可以在这里使用 Markdown，包括**粗体**和_斜体_文本，以及[行内链接](https://docusaurus.io)。
<details>
<summary>嵌套的展开块！里面有惊喜……</summary>
😲😲😲😲😲
</details>
</details>
Details 元素示例
点我展开！
这里是详细内容。
console.log("包括代码块在内的 Markdown 功能都可用");
你可以在这里使用 Markdown，包括粗体和_斜体_文本，以及行内链接。
嵌套的展开块！里面有惊喜……
😲😲😲😲😲
你可能希望将你的 <summary> 保持在单行。请记住，MDX 会为空格创建额外的 HTML <p> 段落。如有疑问，请使用 MDX playground 来排查 <details> 的渲染问题。