跳到主要内容

Markdown Features

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

Learn Markdown

You can learn Markdown in 10 minutes.

Docusaurus uses modern tooling to help you create interactive documentation.

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.

Use the MDX Playground

The MDX playground is your new best friend!

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

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

MDX vs. CommonMark​

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.

The MDX compiler supports 2 formats:

  • The MDX format: a powerful parser allowing the usage of JSX
  • The CommonMark format: a standard-compliant Markdown parser that does not allow the usage of JSX

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

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

how to use 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 files will use the CommonMark format
  • .mdx files will use the MDX format

标准特性​

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

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

img alt

Markdown is declarative

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​

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.

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

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

引言（Quotes）​

我们为 Markdown 中的引言（quotes）标记设置了漂亮的样式：

> Easy to maintain open source documentation websites.
>
> — Docusaurus
http://localhost:3000

Easy to maintain open source documentation websites.

— Docusaurus

<details> 元素​

Markdown 中可以嵌入 HTML 元素。我们为 HTML 中的 details 元素设置了漂亮的样式：

### Details element example

<details>
  <summary>Toggle me!</summary>
  <div>
    <div>This is the detailed content</div>
    <br/>
    <details>
      <summary>
        Nested toggle! Some surprise inside...
      </summary>
      <div>😲😲😲😲😲</div>
    </details>
  </div>
</details>
http://localhost:3000

Details element example

Toggle me!
This is the detailed content

Nested toggle! Some surprise inside...

😲😲😲😲😲