Markdown 功能

Docusaurus 使用 Markdown 作为其主要内容创作格式。

了解 Markdown

您可以在 10 分钟内学习 Markdown 。

Docusaurus 使用现代工具来帮助您创建 交互式文档 。

MDX编译器将 Markdown 文件转换为 React 组件，并允许您在 Markdown 内容中使用 JSX。这使您可以轻松地在内容中插入 React 组件，并创造令人愉悦的学习体验。

使用 MDX Playground

MDX playground 是您新的好朋友！

它是一个非常有用的调试工具，它显示了 MDX 编译器如何将 Markdown 转换为 React。

选项: 选择正确的格式（MDX 或 CommonMark）以及 Docusaurus 使用的以下插件：remark-gfm、remark-directive、rehype-raw。

MDX 与 CommonMark

Docusaurus 使用 MDX 编译器将 .md 和 .mdx 文件编译成 React 组件，但是 语法解释可能因您的设置而异 。

MDX 编译器支持两种格式：

MDX 格式 : 一个强大的解析器，允许使用 JSX
CommonMark 格式 : 一个符合标准的 Markdown 解析器，不允许使用 JSX

默认情况下， Docusaurus v3 出于历史原因对所有文件（包括 .md 文件）使用 MDX 格式 。

可以使用 siteConfig.markdown.format 设置或mdx.format: md前置 matter 选择加入 CommonMark 。

如何使用 CommonMark

如果您计划使用 CommonMark，我们建议使用 siteConfig.markdown.format: 'detect' 设置。合适的格式将根据文件扩展名自动选择：

.md 文件将使用 CommonMark 格式
.mdx 文件将使用 MDX 格式

实验性 CommonMark 支持

CommonMark 支持是 实验性 的，目前有一些限制。

标准功能

Markdown 是一种语法，使您可以以可读的语法编写格式化内容。

### 我的文档章节

带有某些 **粗体** 文本、某些_斜体_文本和 [链接](/) 的 Hello world 消息

![img alt](/img/docusaurus.png)

http://localhost:3000

我的文档章节

带有某些粗体文本、某些_斜体_文本和链接的 Hello world 消息

img alt

Markdown 是声明式的

有些人可能会假设 Markdown 和 HTML 之间存在一对一的关联，例如，! [Preview](/img/docusaurus.png) 将始终变为 <img src="/img/docusaurus.png" alt="Preview" />，按原样。但是，情况并非如此。

Markdown 语法 ! [message](url) 只声明性地告诉 Docusaurus 需要在此处插入图像，但我们可能会执行其他操作，例如将文件路径转换为 URL 路径，因此生成的标记可能与其他 Markdown 渲染器的输出不同，或者与等效 JSX/HTML 代码的简单手工转录不同。

一般来说，您应该只假设标记的_语义_（``` 围栏成为代码块；> 成为引用等），而不是实际编译后的输出。

前置 matter

前置 matter 用于向 Markdown 文件添加元数据。所有内容插件都有自己的前置 matter 模式，并使用前置 matter 来丰富从内容或其他配置推断出的默认元数据。

前置 matter 提供在文件的顶部，用三个破折号 --- 括起来。内容被解析为 YAML 。

---
title: 我的文档标题
more_data:
  - 可以提供
  - 为：对象
    或：数组
---

信息

每个官方插件的 API 文档列出了支持的属性：

增强您的前置 matter

使用 Markdown 配置 parseFrontMatter 函数来提供您自己的前置 matter 解析器，或增强默认解析器。

可以重用默认解析器来将其与您自己的自定义专有逻辑包装在一起。这使得实现方便的前置 matter 转换、快捷方式或与 Docusaurus 插件不支持的前置 matter 使用的外部系统集成成为可能。

docusaurus.config.js
export default {
  markdown: {
    parseFrontMatter: async (params) => {
      // 重用默认解析器
      const result = await params.defaultParseFrontMatter(params);

      // 处理前置 matter 描述占位符
      result.frontMatter.description =
        result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');

      // 创建您自己的前置 matter 快捷方式
      if (result.frontMatter.i_do_not_want_docs_pagination) {
        result.frontMatter.pagination_prev = null;
        result.frontMatter.pagination_next = null;
      }

      // 重命名来自另一个系统的不受支持的前置 matter
      if (result.frontMatter.cms_seo_summary) {
        result.frontMatter.description = result.frontMatter.cms_seo_summary;
        delete result.frontMatter.cms_seo_summary;
      }

      return result;
    },
  },
};

引用

Markdown 引用具有漂亮的样式：

> 易于维护的开源文档网站。
>
> — Docusaurus

http://localhost:3000

易于维护的开源文档网站。

— Docusaurus

详情

Markdown 可以嵌入 HTML 元素，并且 details HTML 元素具有漂亮的样式：

### 详情元素示例

<details>
  <summary>切换我！</summary>

  这是详细内容

  ```js
  console.log("包括代码块在内的 Markdown 功能可用");
  ```

  您可以在此处使用 Markdown，包括 **粗体** 和_斜体_文本以及[内联链接](https://docusaurus.io)
  <details>
    <summary>嵌套切换！里面有一些惊喜……</summary>

    😲😲😲😲😲
  </details>
</details>

http://localhost:3000

详情元素示例

切换我！

这是详细内容

console.log("包括代码块在内的 Markdown 功能可用");

您可以在此处使用 Markdown，包括粗体和_斜体_文本以及内联链接

嵌套切换！里面有一些惊喜……

😲😲😲😲😲

信息

您可能希望将<summary> 保持在一行上。请记住， MDX 为换行符创建额外的 HTML <p> 段落。如有疑问，请使用 MDX playground 来排除<details> 渲染问题。

MDX 与 CommonMark​

标准功能​

我的文档章节

前置 matter​

引用​

详情​

详情元素示例

MDX 与 CommonMark

标准功能

前置 matter

引用

详情