跳到主要内容

Markdown 特性

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

学习 Markdown

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

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

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

使用 MDX 操场

MDX 操场 是您的新好帮手！

这是一个非常有用的调试工具，可以展示 MDX 编译器如何将 Markdown 转换为 React。

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

MDX vs. CommonMark​

Docusaurus 使用 MDX 编译器将 .md 和 .mdx 文件编译为 React 组件，但根据您的设置，语法可能会被不同地解释。

MDX 编译器支持 2 种格式：

  • MDX 格式：一个强大的解析器，允许使用 JSX
  • CommonMark 格式：一个标准兼容的 Markdown 解析器，不允许使用 JSX

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

可以通过 siteConfig.markdown.format 设置或 mdx.format: md 前置元数据来选择使用 CommonMark。

如何使用 CommonMark

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

  • .md 文件将使用 CommonMark 格式
  • .mdx 文件将使用 MDX 格式
实验性 CommonMark 支持

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

标准特性​

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

### 我的文档章节

你好世界消息，包含一些**粗体**文本，一些_斜体_文本，和一个[链接](/)

![图片alt](/img/docusaurus.png)
http://localhost:3000

我的文档章节

你好世界消息，包含一些粗体文本，一些_斜体_文本和一个链接

图片alt

Markdown 是声明性的

有些人可能会假设 Markdown 和 HTML 之间存在一一对应的关系，例如 ![预览](/img/docusaurus.png) 将始终变成 <img src="/img/docusaurus.png" alt="预览" />，就是这样。然而，事实并非如此。

Markdown 语法 ![消息](url) 只是声明性地告诉 Docusaurus 需要在此处插入图像，但我们可能会做其他事情，比如将文件路径转换为 URL 路径，因此生成的标记可能与其他 Markdown 渲染器的输出或手动转录为等效的 JSX/HTML 代码不同。

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

前置元数据​

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

前置元数据位于文件顶部，用三个破折号 --- 包围。内容被解析为 YAML。

---
title: 我的文档标题
更多数据:
  - 可以提供
  - as: 对象
    or: 数组
---
信息

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

增强您的前置元数据

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

可以重用默认解析器，用您自己的自定义专有逻辑包装它。这使得可以实现方便的前置元数据转换、快捷方式，或使用 Docusaurus 插件不支持的外部系统的前置元数据。

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

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

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

      // 重命名来自另一个系统的不受支持的前置元数据
      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 操场 来排查 <details> 渲染问题。