跳到主要内容
版本：3.8.1

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 front matter 选择使用 CommonMark。

如何使用 CommonMark

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

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

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

标准特性​

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

### My Doc Section

Hello world message with some **bold** text, some _italic_ text, and a [link](/)

![img alt](/img/docusaurus.png)
https://:3000

我的文档部分

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

img alt

Markdown 是声明性的

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

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

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

Front matter​

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

Front matter 位于文件的最顶部，由三个破折号 --- 包围。内容解析为 YAML。

---
title: My Doc Title
more_data:
  - Can be provided
  - as: objects
    or: arrays
---
信息

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

增强你的 front matter

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

可以重用默认解析器，并用你自己的自定义专有逻辑对其进行包装。这使得实现方便的 front matter 转换、快捷方式，或与使用 Docusaurus 插件不支持的 front matter 的外部系统集成成为可能。

docusaurus.config.js
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
https://:3000

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

— 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>
https://:3000

Details 元素示例

点击我！

这是详细内容

console.log("Markdown features including the code block are available");

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

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

😲😲😲😲😲

信息

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