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:

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

Configuration in docusaurus.config.js

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

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

Popular Rehype Plugins

Installing and Using Plugins

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

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:

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]

Blog

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

Pages

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

Using Components in Docusaurus MDX

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

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

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

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