Skip to main content

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 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

如果你计划使用 CommonMark，我们推荐 siteConfig.markdown.format: 'detect' 设置。系统会根据文件扩展名自动选择合适的格式：

  • .md 文件将使用 CommonMark 格式
  • .mdx 文件将使用 MDX 格式
CommonMark 支持尚处实验阶段

CommonMark 支持目前处于实验性阶段，并且存在一些局限性。

标准功能​

Markdown 是一种能让你用可读的语法编写格式化内容的语法。

### 我的文档章节

这是一条 Hello world 消息，包含一些**粗体**文本、一些_斜体_文本，以及一个[链接](/)。

![图片替代文本](/img/docusaurus.png)
http://localhost:3000

我的文档章节

这是一条 Hello world 消息，包含一些粗体文本、一些_斜体_文本，以及一个链接。

图片替代文本

Markdown 是声明式的

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

Markdown 语法 ![消息](url) 只是以声明的方式告诉道格龙（Docusaurus），这里需要插入一张图片，但我们可能会做其他事情，比如将文件路径转换为 URL 路径，所以生成的标记可能与其他 Markdown 渲染器或简单地手动转写为等效 JSX/HTML 代码的输出有所不同。

总的来说，你应该只假定标记的语义（例如 ``` 包裹的会变成代码块，> 会变成引用等），而不是它实际编译后的输出。

头部元数据 (Front Matter)​

头部元数据用于为你的 Markdown 文件添加元数据。所有的内容插件都有自己的头部元数据结构，并使用这些元数据来丰富从内容或其他配置中推断出的默认元数据。

头部元数据位于文件的最顶部，由三条短划线 --- 包围。其内容被解析为 YAML。

---
title: 我的文档标题
more_data:
  - 可以作为
  - as: 对象
    or: 数组
---
info

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

增强你的头部元数据

使用 Markdown 配置中的 parseFrontMatter 函数，可以提供你自己的头部元数据解析器，或增强默认的解析器。

复用默认的解析器，并用你自己的定制逻辑来包装它，是完全可行的。这使得实现便捷的头部元数据转换、快捷方式，或与使用道格龙（Docusaurus）插件不支持的头部元数据的外部系统集成成为可能。

docusaurus.config.js
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）
http://localhost:3000

轻松维护开源文档网站。

— 道格龙（Docusaurus）

详情块​

Markdown 可以嵌入 HTML 元素，而 details HTML 元素的样式也同样精美：

### Details 元素示例

<details>
  <summary>点我展开！</summary>

  这里是详细内容。

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

  你可以在这里使用 Markdown，包括**粗体**和_斜体_文本，以及[行内链接](https://docusaurus.io)。
  <details>
    <summary>嵌套的展开块！里面有惊喜……</summary>

    😲😲😲😲😲
  </details>
</details>
http://localhost:3000

Details 元素示例

点我展开！

这里是详细内容。

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

你可以在这里使用 Markdown，包括粗体和_斜体_文本，以及行内链接。

嵌套的展开块！里面有惊喜……

😲😲😲😲😲

info

你可能希望将你的 <summary> 保持在单行。请记住，MDX 会为空格创建额外的 HTML <p> 段落。如有疑问，请使用 MDX playground 来排查 <details> 的渲染问题。

Last updated on