Docusaurus Markdown: Features Beyond Standard Syntax

Docusaurus compiles every .md and .mdx file with the MDX compiler. That gives you admonitions, tabs, code block titles, line highlighting, and React components on top of standard Markdown. It also means a few habits from GitHub Markdown break. This page collects the Docusaurus-specific syntax in one place, with copy-paste examples and the pitfalls to check before you paste in an old README.

What Is Docusaurus Used For?

It's Meta's open-source static site generator for documentation. You write pages in Markdown or MDX, drop them into a docs folder, and it builds a React site with a sidebar, versioning, search, and translations. Meta uses it for projects such as React Native and Jest, and the project's showcase lists hundreds of other open-source and company docs sites.

It's free under the MIT license and there's no hosted tier to pay for. Version 3.10.2 is current as of September 2026, and a new site starts with one command:

npx create-docusaurus@latest my-website classic

Add --typescript for a TypeScript config. The scaffold includes a docs folder, a blog folder, and a docusaurus.config.js where most of the options below live.

MDX or CommonMark: How Docusaurus Parses Your Files

This is the first thing to understand, because it explains every surprising error. The MDX compiler supports two formats, and Docusaurus v3 uses the MDX format for all files by default, including plain .md files. That's a historical choice, and you can change it in docusaurus.config.js:

markdown.format value	.md files	.mdx files	When to use it
mdx (default)	MDX	MDX	You want JSX and imports everywhere
md	CommonMark	CommonMark	You never use JSX
detect	CommonMark	MDX	Recommended by the docs if you want CommonMark for .md

export default {
  markdown: {
    format: 'detect',
  },
};

A single file can also opt in through front matter with mdx.format: md. The docs mark CommonMark support as experimental and link to an issue listing its limitations. The practical advice is to keep the default and learn the handful of characters MDX treats specially. The next sections cover them.

Docusaurus Admonitions and Callouts

Admonitions are the colored callout boxes and the most-used Docusaurus extra. The syntax is a directive fence of three colons with a type keyword. Five types ship with the classic theme: note, tip, info, warning, and danger.

:::tip[Use a title in square brackets]

Admonition bodies accept **Markdown**, `code`, and [links](#).

:::

:::warning

Leave a blank line after the opening fence and before the closing one, or Prettier may reformat the block into invalid syntax.

:::

The admonitions page also documents attributes in curly braces after the title, such as a CSS class or an ID. Nesting works by adding more colons to the outer fence (:::: around :::). The older :::note Your Title form still works because the mdx1Compat.admonitions option is on by default in v3.

If you're used to GitHub's > [!NOTE] alerts, the two don't mix. Our Markdown callout guide compares the platform syntaxes; here, only the colon fence renders as a box.

Docusaurus Code Block Features

Fenced code blocks gain a metadata string after the language. The code blocks page documents four features you'll use constantly:

```js title="src/config.js" showLineNumbers {2,4-5}
const site = 'docs';
const version = 3;
// highlight-next-line
const format = 'mdx';
export { site, version, format };
```

• title="..." renders a filename bar above the block.
• {2,4-5} highlights lines 2, 4, and 5. Ranges and single lines can be mixed.
• // highlight-next-line, // highlight-start, and // highlight-end are magic comments that do the same job from inside the code and are removed from the output.
• showLineNumbers adds a gutter; showLineNumbers=3 starts counting at 3.

Live editable React blocks need one more package. Install @docusaurus/theme-live-codeblock, add it to themes in the config, and tag a block ```jsx live. The rest of the metadata syntax is the same. For the language identifiers themselves, the code block guide lists the common tags.

Front Matter, Heading IDs, Tabs, and Details

Front matter. Every doc accepts a YAML block at the top. The keys you'll set most, from the docs plugin reference, are id, title, sidebar_label, sidebar_position, slug, description, tags, and keywords. Blog posts add authors and date.

---
id: install
title: Installation
sidebar_position: 1
description: Install the CLI in under a minute.
tags: [setup]
---

Heading IDs. Every heading gets a generated ID. To pin one, append {#custom-id} to the heading text; the syntax works in both MDX and CommonMark files, and links such as [see install](#custom-id) then survive title edits.

Tabs. Tabs are React components, so they need an import at the top of an MDX file:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="npm" label="npm" default>
    Run `npm install`.
  </TabItem>
  <TabItem value="pnpm" label="pnpm">
    Run `pnpm install`.
  </TabItem>
</Tabs>

Details. Plain HTML details and summary elements render as styled collapsible boxes, no import required. The collapsible section guide shows the same element on GitHub.

Blog summaries. In a blog post, everything above <!-- truncate --> becomes the list-page excerpt. In an .mdx post, use the MDX comment form {/* truncate */} instead; the docs state both markers are supported.

What Breaks When You Paste Markdown Into Docusaurus?

Because the default parser is MDX, a few things that GitHub renders happily stop the build. The Docusaurus v3 migration guide lists them, and they're easy to fix once you know the pattern.

Standard Markdown habit	What MDX does	Fix
A { in prose, such as a code sample written inline	Tries to parse a JavaScript expression and fails	Wrap in backticks, or escape as \{
A bare < followed by a digit or a word, such as version <5 or Array<T>	Reads it as the start of a JSX tag	Backticks, \<, or &lt;
GFM autolinks in angle brackets, such as an email or URL wrapped in < and >	Fails with an unexpected character error	Write the bare URL or a [text](url) link
Indented code blocks (four spaces)	Rendered as a paragraph, not code	Use a fenced block
HTML comments	Officially unsupported; allowed only while mdx1Compat.comments stays on	Prefer {/* ... */} in MDX files
Unclosed HTML tags such as <br>	Build error	Self-close: <br />

The table on its own is the reason we recommend drafting in a plain Markdown editor first, checking the render, and then adding Docusaurus extras. Paste the sample below into the editor to see how standard GFM looks before MDX gets involved. You can also run it through the Markdown to HTML converter to inspect the exact markup:

Two more habits to drop. Lower-case custom elements aren't mapped to theme components, so <callout> renders as an unknown tag rather than an admonition. And a stray * at the start of a word is parsed more strictly than in GitHub, so check emphasis that hugs punctuation.

What survives unchanged

The good news is that ordinary GFM is fully supported through remark-gfm. Tables, task lists, strikethrough, footnotes, and fenced code all render as they do on GitHub. Standard links and images work, and relative links to other .md files are rewritten to site URLs at build time, which is why [install](./install.md) keeps working after deployment. Headings become sidebar and table-of-contents entries automatically, from H2 down to H3 by default.

Common Docusaurus Markdown mistakes

Adding admonition fences without blank lines. Prettier collapses :::note and its body onto adjacent lines and the box stops rendering. Keep a blank line after the opening fence and before the closing one.

Importing Tabs in a .md file with format: detect. Under detect, .md files are CommonMark, and CommonMark has no imports. Rename the file to .mdx or keep the default MDX format.

Putting a code fence directly inside a TabItem. MDX needs a blank line before and after the fence to leave JSX mode. Without it, the backticks are literal text inside the tab.

Docusaurus Examples: One Page That Uses Everything

Here's a compact doc that exercises most of the extras above. Save it as docs/quickstart.mdx in a fresh classic site and it builds without changes.

---
id: quickstart
title: Quickstart
sidebar_position: 2
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Quickstart {#quickstart}

:::info[Before you start]

You need Node.js installed. Check with `node -v`.

:::

## Install {#install}

<Tabs>
  <TabItem value="npm" label="npm" default>

```bash title="terminal"
npm install my-tool
```

  </TabItem>
  <TabItem value="pnpm" label="pnpm">

```bash title="terminal"
pnpm add my-tool
```

  </TabItem>
</Tabs>

## Configure {#configure}

```js title="my-tool.config.js" showLineNumbers {3}
export default {
  input: 'src',
  output: 'dist',
};
```

<details>
  <summary>Why a config file?</summary>

  Because CLI flags get long. See the [install step](#install).

</details>

:::warning

Line 3 above is highlighted with the `{3}` metadata string.

:::

A few things to notice. The front matter sets the sidebar order and the URL. The info admonition carries a custom title in square brackets. Each heading pins its own ID so the #install link in the details block keeps working if you rename the section later. The config block combines a title, line numbers, and a highlighted line in one metadata string.

Note the blank lines inside each TabItem around the code fence. MDX needs them to switch from JSX back to Markdown; without them the fence is treated as literal text. Mermaid diagrams and KaTeX math are available too, through @docusaurus/theme-mermaid with markdown.mermaid: true and the remark-math plus rehype-katex plugins respectively.

Docusaurus Markdown FAQ

Writing for Docusaurus is standard Markdown plus a short list of extras: colon-fenced admonitions, code block metadata, front matter, heading IDs, and MDX components such as tabs. Learn the four characters MDX treats specially and the rest is familiar. Draft in the editor, confirm the plain render, then add the Docusaurus features. If you also maintain a README for the same project, the README guide covers the GitHub side.