跳到主要内容
版本：Canary 🚧

Markdown 特性

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

学习 Markdown

你可以10分钟速通 Markdown。

Docusaurus 使用现代化工具来帮助你轻松撰写交互式文档。

MDX 编译器将 Markdown 文件转换成 React 组件，并允许您在 Markdown 内容中使用 JSX。 这使得您能够轻松地将 React 组件在您的内容中进行交互，并创造愉快的学习体验。

使用 MDX Playground

MDX 游乐场 是您最好的朋友！

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

选项: 选择正确的格式 (MDX 或 CommonMark) 和以下插件: remark-gfm, remark-directive, rehype-raw

MDX 与 CommonMark 的对比​

Docusaurus 会通过 MDX 编译器把 .md 和 .mdx 文件都编译成 React 组件。 but the syntax can be interpreted differently depending on your settings.

MDX 编译器支持 2 种格式：

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

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

It is possible to opt-in for CommonMark using the siteConfig.markdown.format setting or the mdx.format: md front matter.

如何使用 CommonMark

If you plan to use CommonMark, we recommend the siteConfig.markdown.format: 'detect' setting. The appropriate format will be selected automatically, based on file extensions:

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

此功能是实验性的 ，目前有几个限制。

标准功能​

Markdown 是一种能让你撰写易读的格式化内容的语法。

### 我的文档章节

一些文本，包括**粗体**、_斜体_，和[链接](/)

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

我的文档章节

一些文本，包括粗体、斜体，和链接

图片 alt 文本

Markdown 是声明式的

Some may assume a 1-1 correlation between Markdown and HTML, e.g., ![Preview](/img/docusaurus.png) will always become <img src="/img/docusaurus.png" alt="Preview" />, as-is. However, that is not the case.

The Markdown syntax ![message](url) only declaratively tells Docusaurus that an image needs to be inserted here, but we may do other things like transforming a file path to URL path, so the generated markup may differ from the output of other Markdown renderers, or a naïve hand-transcription to the equivalent JSX/HTML code.

In general, you should only assume the semantics of the markup (``` fences become code blocks; > becomes quotes, etc.), but not the actual compiled output.

前言​

你可以用前言 (front matter) 来给你的 Markdown 文件添加元数据。 All content plugins have their own front matter schema, and use the front matter to enrich the default metadata inferred from the content or other configuration.

前言是在文件的最顶端给出的，两端由三个横线 --- 包围。 内容被解析为 YAML

---
title: 我的文档标题
其他内容:
  - 可以以
  - 对象: 或者
    数组: 的形式给出
---
信息

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

增强您的前言

Use the Markdown config parseFrontMatter function to provide your own front matter parser, or to enhance the default parser.

It is possible to reuse the default parser to wrap it with your own custom proprietary logic. This makes it possible to implement convenient front matter transformations, shortcuts, or to integrate with external systems using front matter that Docusaurus plugins do not support.

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 引文有着漂亮的样式：

> 易于维护开源文档网站。
>
> — Docusaurus
http://localhost:3000

易于维护开源文档网站。

— Docusaurus

细节​

Markdown 可以嵌入 HTML 元素，and details HTML elements are beautifully styled:

### 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.io)
  <details>
    <summary>Nested toggle! Some surprise inside...</summary>

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

Details element example

Toggle me!

This is the detailed content

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

You can use Markdown here including bold and italic text, and inline link

Nested toggle! Some surprise inside...

😲😲😲😲😲

信息

您可能想要将您的 <summary> 保留在单行上。 Keep in mind that MDX creates extra HTML <p> paragraphs for line breaks.. 如有疑问，请使用 MDX 播放场 来排除 <details> 呈现问题。