Skip to main content

Markdown Features

Docusaurus uses Markdown as the primary format for writing documentation,
but it extends it with MDX, enabling React components inside Markdown files.

Quick Start

Need a refresher? Learn Markdown in 10 minutes to get started quickly.

MDX Power​

MDX transforms Markdown into React components, allowing you to mix text, JSX, and interactive UI elements in a single file.
This is what makes Docusaurus docs highly customizable and interactive.

Example:

hello.mdx
# Hello World

Welcome to my page!

<MyComponent />

This renders both the Markdown heading and the <MyComponent /> React component.

MDX Playground

Use the MDX Playground to see how your Markdown+JSX compiles to React.

MDX vs CommonMark​

Docusaurus supports two Markdown parsing modes:

  • MDX format – Allows JSX and components.
  • CommonMark format – Standard Markdown with no JSX.

By default, .md and .mdx files both use MDX. You can opt in to CommonMark with the markdown.format config or mdx.format: md front matter.

docusaurus.config.js
export default {
  markdown: {
    format: 'detect', // auto: .md → CommonMark, .mdx → MDX
  },
};
Experimental

CommonMark support is still experimental and may differ from other renderers.

Standard Markdown Features​

All familiar Markdown syntax works:

hello.mdx
### My Section

Some **bold** text, some _italic_, and a [link](/).
http://localhost:3000/docs/hello

My Section

Some bold text, some italic, and a link.

Front Matter​

Front matter lets you add metadata to your Markdown files. It’s written in YAML between triple dashes at the top of a file.

getting-started.mdx
---
title: Getting Started
description: Quick introduction to my guide
tags: [intro, tutorial]
---

Different plugins support different front matter fields:

You can even customize the parser:

docusaurus.config.js
export default {
  markdown: {
    parseFrontMatter: async (params) => {
      const result = await params.defaultParseFrontMatter(params);
      if (result.frontMatter.shortTitle) {
        result.frontMatter.title = result.frontMatter.shortTitle;
      }
      return result;
    },
  },
};

Quotes and Callouts​

Docusaurus makes open source documentation easy.

— The Team

Quotes render with elegant styling.

Details & Collapsible Sections​

Docusaurus supports <details> for collapsible content:

<details>
  <summary>Click to expand</summary>

  Hidden content **with Markdown** inside!
</details>
http://localhost:3000
Click to expand

Hidden content with Markdown inside!

Assets & Images​

Use relative paths to reference images and files:

![Logo](/img/nav-logo.jpg)
http://localhost:3000

Logo

Docusaurus will automatically optimize and resolve the asset URLs.

With Markdown + MDX, you can start with simple text and gradually enhance pages with dynamic React components, interactive demos, and custom UI elements—all in one file.