Markdown 功能

¥Markdown Features

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

¥Docusaurus uses Markdown as its main content authoring format.

学习 Markdown

你可以 10 分钟学会 Markdown。

¥You can learn Markdown in 10 minutes.

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

¥Docusaurus uses modern tooling to help you create interactive documentation.

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

¥The MDX compiler transforms Markdown files to React components, and allows you to use JSX in your Markdown content. This enables you to easily interleave React components within your content, and create delightful learning experiences.

使用 MDX Playground

MDX 在线运行 是你最好的新朋友！

¥The MDX playground is your new best friend!

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

¥It is a very helpful debugging tool that shows how the MDX compiler transforms Markdown to React.

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

¥Options: select the right format (MDX or CommonMark) and the following plugins Docusaurus uses: remark-gfm, remark-directive, rehype-raw.

MDX 对比 CommonMark

¥MDX vs. CommonMark

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

¥Docusaurus compiles both .md and .mdx files to React components using the MDX compiler, but the syntax can be interpreted differently depending on your settings.

MDX 编译器支持 2 种格式：

¥The MDX compiler supports 2 formats:

• MDX 格式：一个强大的解析器，允许使用 JSX

  ¥The MDX format: a powerful parser allowing the usage of JSX

• 通用标记格式：一个符合标准的 Markdown 解析器，不允许使用 JSX

  ¥The CommonMark format: a standard-compliant Markdown parser that does not allow the usage of JSX

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

¥By default, Docusaurus v3 uses the MDX format for all files (including .md files) for historical reasons.

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

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

如何使用 CommonMark

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

¥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 格式

  ¥.md files will use the CommonMark format

• .mdx 文件将使用 MDX 格式

  ¥.mdx files will use the MDX format

实验性 CommonMark 支持

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

¥The CommonMark support is experimental and currently has a few limitations.

标准功能

¥Standard features

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

¥Markdown is a syntax that enables you to write formatted content in a readable syntax.

### My Doc Section

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

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

http://localhost:3000

My Doc Section

Hello world message with some bold text, some italic text and a link

Markdown is declarative

有些人可能会假设 Markdown 和 HTML 之间存在 1-1 的相关性，例如 ![Preview](/img/docusaurus.png) 总是会变成 <img src="/img/docusaurus.png" alt="Preview" />。然而，事实并非如此。

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

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

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

一般来说，你应该只假设标记的语义（````` 栅栏变成 代码块；> 变成 quotes，等等），而不是实际的编译输出。

¥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

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

¥Front matter is used to add metadata to your Markdown file. 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。

¥Front matter is provided at the very top of the file, enclosed by three dashes ---. The content is parsed as YAML.

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

信息

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

¥The API documentation of each official plugin lists the supported attributes:

• 文档前面的内容

  ¥Docs front matter

• 博客前沿问题

  ¥Blog front matter

• 页首内容

  ¥Pages front matter

增强你的头条新闻

使用 Markdown 配置 parseFrontMatter 功能 提供你自己的前端解析器，或增强默认解析器。

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

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

¥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;
    },
  },
};

引号

¥Quotes

Markdown 引号的样式很漂亮：

¥Markdown quotes are beautifully styled:

> Easy to maintain open source documentation websites.
>
> — Docusaurus

http://localhost:3000

Easy to maintain open source documentation websites.

— Docusaurus

细节

¥Details

Markdown 可以嵌入 HTML 元素，details 个 HTML 元素的样式很漂亮：

¥Markdown can embed HTML elements, 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.nodejs.cn)
  <details>
    <summary>Nested toggle! Some surprise inside...</summary>

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

<BrowserWindow>

<h3>Details element example</h3>

<details>
  <summary>Toggle me!</summary>

  This is the detailed content

  ```

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

¥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.nodejs.cn)
<details>
  <summary>Nested toggle! Some surprise inside...</summary>

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

</BrowserWindow>
```

:::info[信息]

你可能希望将 `<summary>` 放在一行上。请记住 [MDX 创建额外的 HTML `<p>` 段落用于换行。](https://mdx.nodejs.cn/migrating/v2/#jsx)。如有疑问，请使用 [MDX 在线运行](https://mdx.nodejs.cn/playground/) 解决 `<details>` 渲染问题。

¥You may want to keep your `<summary>` on a single line. Keep in mind that [MDX creates extra HTML `<p>` paragraphs for line breaks.](https://mdx.nodejs.cn/migrating/v2/#jsx). When in doubt, use the [MDX playground](https://mdx.nodejs.cn/playground/) to troubleshoot `<details>` rendering problems.

:::