Markdown 功能
Docusaurus 使用 Markdown 作为其主要内容创作格式。
您可以在 10 分钟内学会 Markdown。
Docusaurus 使用现代工具来帮助您创建交互式文档。
MDX 编译器将Markdown 文件转换为 React 组件，并允许您在 Markdown 内容中使用 JSX。这使您能够轻松地在内容中插入 React 组件，并创造愉快的学习体验。
MDX 游乐场 是您新的好朋友！
它是一个非常有用的调试工具，可以显示 MDX 编译器如何将 Markdown 转换为 React。
选项：选择正确的格式（MDX 或 CommonMark）以及 Docusaurus 使用的以下插件：remark-gfm、remark-directive、rehype-raw。
MDX 与 CommonMark
Docusaurus 使用 MDX 编译器将 .md 和 .mdx 文件都编译成 React 组件，但语法可能会根据您的设置进行不同的解释。
MDX 编译器支持 2 种格式
- MDX 格式：一个功能强大的解析器，允许使用 JSX
- CommonMark 格式：一个符合标准的 Markdown 解析器，不允许使用 JSX
默认情况下，Docusaurus v3 对所有文件（包括 .md 文件）使用 MDX 格式，出于历史原因。
可以使用 siteConfig.markdown.format 设置或 format: md 前置 matter 来选择使用 CommonMark。
如果您计划使用 CommonMark，我们建议使用 siteConfig.markdown.format: 'detect' 设置。将根据文件扩展名自动选择合适的格式
.md文件将使用 CommonMark 格式.mdx文件将使用 MDX 格式
CommonMark 支持处于实验阶段，目前存在一些 限制。
标准功能
Markdown 是一种语法，使您能够以易于阅读的语法编写格式化内容。
### My Doc Section
Hello world message with some **bold** text, some _italic_ text, and a [link](/)
Markdown 是声明式的
有些人可能会假设 Markdown 和 HTML 之间存在 1 对 1 的对应关系，例如， 将始终变为 <img src="/img/docusaurus.png" alt="Preview" />，按原样。但是，情况并非如此。
Markdown 语法  仅声明性地告诉 Docusaurus 需要在此处插入图像，但我们可能会执行其他操作，例如将 文件路径转换为 URL 路径，因此生成的标记可能与其他 Markdown 渲染器的输出或对等 JSX/HTML 代码的简单手工转录不同。
前置 matter
前置 matter 用于向 Markdown 文件添加元数据。所有内容插件都有自己的前置 matter 模式，并使用前置 matter 来丰富从内容或其他配置推断出的默认元数据。
前置 matter 提供在文件的顶部，用三个破折号 --- 括起来。内容被解析为 YAML。
---
title: My Doc Title
more_data:
- Can be provided
- as: objects
or: arrays
---
每个官方插件的 API 文档都列出了支持的属性
使用 Markdown 配置 parseFrontMatter 函数 来提供您自己的前置 matter 解析器，或增强默认解析器。
可以重用默认解析器来用您自己的自定义专有逻辑将其包装起来。这使得实现方便的前置 matter 转换、快捷方式或与 Docusaurus 插件不支持的前置 matter 使用的外部系统集成成为可能。
export default {
markdown: {
parseFrontMatter: async (params) => {
// Reuse the default parser
const result = await params.defaultParseFrontMatter(params);
// Process front matter description placeholders
result.frontMatter.description =
result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');
// Create your own front matter shortcut
if (result.frontMatter.i_do_not_want_docs_pagination) {
result.frontMatter.pagination_prev = null;
result.frontMatter.pagination_next = null;
}
// Rename an unsupported front matter coming from another system
if (result.frontMatter.cms_seo_summary) {
result.frontMatter.description = result.frontMatter.cms_seo_summary;
delete result.frontMatter.cms_seo_summary;
}
return result;
},
},
};
引用
Markdown 引用具有漂亮的样式
> Easy to maintain open source documentation websites.
>
> — Docusaurus
易于维护开源文档网站。
— Docusaurus
详细信息
Markdown 可以嵌入 HTML 元素，并且 details HTML 元素具有漂亮的样式
### Details element example
<details>
<summary>Toggle me!</summary>
This is the detailed content
```js
console.log("Markdown features including the code block are available");
```
You can use Markdown here including **bold** and _italic_ text, and [inline link](https://docusaurus.org.cn)
<details>
<summary>Nested toggle! Some surprise inside...</summary>
😲😲😲😲😲
</details>
</details>
详细信息元素示例
切换我！
这是详细内容
console.log("Markdown features including the code block are available");
您可以在此处使用 Markdown，包括粗体和斜体文本，以及 内联链接
嵌套切换！内部有一些惊喜……
😲😲😲😲😲
您可能希望将 <summary> 保留在一行上。请记住，MDX 为换行符创建额外的 HTML <p> 段落。。如有疑问，请使用 MDX 游乐场 来解决 <details> 渲染问题。