MDX in Docusaurus

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

Docusaurus is probably the most popular docs framework that uses MDX natively. Every .mdx (and .md) file you write gets compiled into a React component. You get markdown simplicity with full component power — no weird workarounds needed.

How Docusaurus Processes MDX

Here's what happens when Docusaurus builds your site:

File Discovery — It scans your content directories (docs, blog, pages)
Frontmatter Extraction — YAML frontmatter gets parsed for metadata
MDX Compilation — Content goes through the MDX pipeline with remark/rehype plugins
React Rendering — The compiled MDX renders as a React component inside your theme

Example

graph LR A[.mdx File] --> B[Frontmatter Parser] B --> C[MDX Compiler] C --> D[Remark Plugins] D --> E[Rehype Plugins] E --> F[React Component]

Configuration in docusaurus.config.js

All the MDX behavior lives in your config file. Here's a full example with comments:

Example

const config = { title: 'My Documentation', url: 'https://docs.example.com', baseUrl: '/', // MDX-related configuration lives inside presets or plugins presets: [ [ 'classic', /** @type {import('@docusaurus/preset-classic').Options} */ ({ docs: { sidebarPath: './sidebars.js', // Enable MDX for .md files too remarkPlugins: [ [require('@docusaurus/remark-plugin-npm2yarn'), { sync: true }], require('remark-math'), ], rehypePlugins: [ require('rehype-katex'), ], // Use .mdx extension by default // Docusaurus treats both .md and .mdx as MDX }, blog: { remarkPlugins: [require('remark-math')], rehypePlugins: [require('rehype-katex')], }, pages: { remarkPlugins: [require('remark-math')], }, }), ], ], // Global markdown configuration markdown: { format: 'mdx', // 'mdx' | 'md' | 'detect' mermaid: true, // Enable Mermaid diagrams mdx1Compat: { comments: true, // Allow HTML comments admonitions: true, // Legacy admonition syntax headingIds: true, // Auto heading IDs }, }, }; module.exports = config;

:::tip Format Detection Setting format: 'detect' tells Docusaurus to use MDX processing for .mdx files and standard CommonMark for .md files. Handy when you're migrating from plain Markdown and can't convert everything at once. :::

MDX Plugins in Docusaurus

Docusaurus supports two types of plugins:

Remark plugins — operate on the Markdown AST (before HTML)
Rehype plugins — operate on the HTML AST (after conversion)

Popular Remark Plugins

Plugin	Purpose
`remark-math`	LaTeX math expressions
`@docusaurus/remark-plugin-npm2yarn`	Auto npm/yarn/pnpm tabs
`remark-gfm`	GitHub Flavored Markdown (included by default)
`remark-images`	Optimized image handling

Popular Rehype Plugins

Plugin	Purpose
`rehype-katex`	Render math with KaTeX
`rehype-prism-plus`	Enhanced code highlighting

Installing and Using Plugins

bash example

npm install remark-math rehype-katex

Example

// Add to your docs configuration docs: { remarkPlugins: [require('remark-math')], rehypePlugins: [require('rehype-katex')], }

Once remark-math and rehype-katex are configured, you can write LaTeX directly in MDX:

mdx example

The quadratic formula is: $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$

File Conventions

Docusaurus has specific rules for how files map to URLs.

Directory Structure

my-docusaurus-site/ ├── docs/ # Documentation pages │ ├── intro.mdx │ ├── tutorial/ │ │ ├── _category_.json # Category metadata │ │ ├── getting-started.mdx │ │ └── advanced.mdx ├── blog/ # Blog posts │ ├── 2024-01-15-first-post.mdx │ └── authors.yml ├── src/ │ └── pages/ # Standalone pages │ ├── index.mdx │ └── about.mdx └── docusaurus.config.js

File Naming Conventions

Docs: File name becomes the URL slug (getting-started.mdx → /docs/getting-started)
Blog: Date-prefixed names (2024-01-15-title.mdx → /blog/2024/01/15/title)
Pages: Direct mapping (about.mdx → /about)

Frontmatter in Docusaurus

Each content type has its own frontmatter fields:

yaml title="docs/example.mdx" example

Docs vs Blog vs Pages

Docusaurus gives you three content types. Each works differently.

Docs

Connected to sidebars for navigation
Support versioning for API docs
Have previous/next navigation
URL pattern: /docs/[path]

mdx title="docs/getting-started.mdx" example

---
sidebar_position: 1
---

# Getting Started

Welcome to the documentation!

Blog

Organized by date with an RSS feed
Support authors and reading time
Have archive and tag pages
URL pattern: /blog/[date]/[slug]

Example

--- title: "v2.0 Release" authors: [team] tags: [release, announcement] --- We're excited to announce version 2.0! {/* truncate */} Full blog post content here...

Pages

Standalone React pages
No sidebar or navigation context
Full layout control
URL pattern: /[filename]

mdx title="src/pages/about.mdx" example

---
title: About Us
---

# About Our Project

This is a standalone page with full MDX support.

Using Components in Docusaurus MDX

Docusaurus has several built-in components you can import in any MDX file:

mdx example

import CodeBlock from '@theme/CodeBlock';
import BrowserWindow from '@site/src/components/BrowserWindow';

<BrowserWindow url="https://example.com">
  This content appears inside a browser frame mockup.
</BrowserWindow>

:::info Visual Result When rendered, users see a styled browser window chrome (address bar, navigation buttons) wrapping your content. Great for showing how something looks in a real browser. :::

Best Practices for Docusaurus MDX

Use frontmatter consistently — Always include title, description, and sidebar_position
Use built-in components first — Tabs, Admonitions, and CodeBlocks before rolling your own
Keep imports at the top — All import statements go right after frontmatter
Use relative links — Link between docs with relative paths so versioning doesn't break things
Prefer MDX over custom React — MDX keeps content accessible to non-developers on the team

Example

{/* ✅ Good: relative link */} See the [installation guide](./installation.mdx) for details. {/* ❌ Avoid: absolute link (breaks versioning) */} See the [installation guide](/docs/installation) for details.

That's the Docusaurus MDX overview. The following pages cover specific features — admonitions, tabs, code blocks — in detail.

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

How Docusaurus Processes MDX

Here's what happens when Docusaurus builds your site:

File Discovery — It scans your content directories (docs, blog, pages)
Frontmatter Extraction — YAML frontmatter gets parsed for metadata
MDX Compilation — Content goes through the MDX pipeline with remark/rehype plugins
React Rendering — The compiled MDX renders as a React component inside your theme

Example

graph LR A[.mdx File] --> B[Frontmatter Parser] B --> C[MDX Compiler] C --> D[Remark Plugins] D --> E[Rehype Plugins] E --> F[React Component]

Configuration in docusaurus.config.js

All the MDX behavior lives in your config file. Here's a full example with comments:

Example

MDX Plugins in Docusaurus

Docusaurus supports two types of plugins:

Remark plugins — operate on the Markdown AST (before HTML)
Rehype plugins — operate on the HTML AST (after conversion)

Popular Remark Plugins

Plugin	Purpose
`remark-math`	LaTeX math expressions
`@docusaurus/remark-plugin-npm2yarn`	Auto npm/yarn/pnpm tabs
`remark-gfm`	GitHub Flavored Markdown (included by default)
`remark-images`	Optimized image handling

Popular Rehype Plugins

Plugin	Purpose
`rehype-katex`	Render math with KaTeX
`rehype-prism-plus`	Enhanced code highlighting

Installing and Using Plugins

bash example

npm install remark-math rehype-katex

Example

// Add to your docs configuration docs: { remarkPlugins: [require('remark-math')], rehypePlugins: [require('rehype-katex')], }

Once remark-math and rehype-katex are configured, you can write LaTeX directly in MDX:

mdx example

The quadratic formula is: $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$

File Conventions

Docusaurus has specific rules for how files map to URLs.

Directory Structure

File Naming Conventions

Docs: File name becomes the URL slug (getting-started.mdx → /docs/getting-started)
Blog: Date-prefixed names (2024-01-15-title.mdx → /blog/2024/01/15/title)
Pages: Direct mapping (about.mdx → /about)

Frontmatter in Docusaurus

Each content type has its own frontmatter fields:

yaml title="docs/example.mdx" example

Docs vs Blog vs Pages

Docusaurus gives you three content types. Each works differently.

Docs

Connected to sidebars for navigation
Support versioning for API docs
Have previous/next navigation
URL pattern: /docs/[path]

mdx title="docs/getting-started.mdx" example

---
sidebar_position: 1
---

# Getting Started

Welcome to the documentation!

Blog

Organized by date with an RSS feed
Support authors and reading time
Have archive and tag pages
URL pattern: /blog/[date]/[slug]

Example

--- title: "v2.0 Release" authors: [team] tags: [release, announcement] --- We're excited to announce version 2.0! {/* truncate */} Full blog post content here...

Pages

Standalone React pages
No sidebar or navigation context
Full layout control
URL pattern: /[filename]

mdx title="src/pages/about.mdx" example

---
title: About Us
---

# About Our Project

This is a standalone page with full MDX support.

Using Components in Docusaurus MDX

Docusaurus has several built-in components you can import in any MDX file:

mdx example

import CodeBlock from '@theme/CodeBlock';
import BrowserWindow from '@site/src/components/BrowserWindow';

<BrowserWindow url="https://example.com">
  This content appears inside a browser frame mockup.
</BrowserWindow>

:::info Visual Result When rendered, users see a styled browser window chrome (address bar, navigation buttons) wrapping your content. Great for showing how something looks in a real browser. :::

Best Practices for Docusaurus MDX

Use frontmatter consistently — Always include title, description, and sidebar_position
Use built-in components first — Tabs, Admonitions, and CodeBlocks before rolling your own
Keep imports at the top — All import statements go right after frontmatter
Use relative links — Link between docs with relative paths so versioning doesn't break things
Prefer MDX over custom React — MDX keeps content accessible to non-developers on the team

Example

That's the Docusaurus MDX overview. The following pages cover specific features — admonitions, tabs, code blocks — in detail.