Markdown Features

Docusaurus uses Markdown as its main content authoring format.

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.

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 mdx.format: md front matter.

Standard features

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

Markdown

### My Doc Section

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

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

mdx-code-block

<BrowserWindow>

<h3>My Doc Section</h3>

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

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

</BrowserWindow>

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.

Markdown

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

enhance your front matter

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

Quotes

Markdown quotes are beautifully styled:

Markdown

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

Easy to maintain open source documentation websites.

— Docusaurus

Details

Markdown can embed HTML elements, and details HTML elements are beautifully styled:

Markdown

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

mdx-code-block

<BrowserWindow>

<h3>Details element example</h3>

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

</BrowserWindow>

Tables

Markdown tables are supported via GitHub Flavored Markdown (GFM). They are an excellent way to display structured data in your documentation.

Markdown

| Feature    | Support | Description                       |
| :--------- | :------ | :-------------------------------- |
| GFM Tables | ✅ Yes  | Standard Markdown table syntax    |
| Alignment  | ✅ Yes  | Left, center, and right alignment |

mdx-code-block

<BrowserWindow>

| Feature    | Support | Description                       |
| :--------- | :------ | :-------------------------------- |
| GFM Tables | ✅ Yes  | Standard Markdown table syntax    |
| Alignment  | ✅ Yes  | Left, center, and right alignment |

</BrowserWindow>