Complete MDX Cheatsheet

Everything you need to look up about MDX syntax — Markdown basics, JSX patterns, frontmatter, imports/exports, and expressions — all on one page.

Bookmark this. Come back when you forget a syntax. That's what it's here for.

Markdown Syntax Reference

Text Formatting

Syntax	Output	HTML
`bold`	bold	`<strong>`
`italic`	italic	`<em>`
`~~strikethrough~~`	~~strikethrough~~	`<del>`
` inline code `	`inline code`	`<code>`
`link`	link	`<a href>`
`!alt`	Image	`<img>`

Headings

mdx example

# Heading 1        → <h1>
## Heading 2       → <h2>
### Heading 3      → <h3>
#### Heading 4     → <h4>
##### Heading 5    → <h5>
###### Heading 6   → <h6>

Output

Heading 1  (largest, page title)
Heading 2  (section title)
Heading 3  (subsection)
Heading 4  (small section)
Heading 5  (fine detail)
Heading 6  (smallest)

Lists

Example

{/* Unordered */} - Item one - Item two - Nested item - Another nested {/* Ordered */} 1. First 2. Second 3. Third {/* Task list (with GFM plugin) */} - [x] Completed - [ ] Not yet done

Blockquotes

mdx example

> Single line quote

> Multi-line quote
> continues on the next line.
>
> New paragraph in the same quote.

Code Blocks

`mdx example

const x = 42;

Example

function App() { return <h1>Hello</h1>; }

Example

npm install @mdx-js/react

Example

Tables

mdx example

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Cell 1       | Cell 2         | Cell 3        |
| Cell 4       | Cell 5         | Cell 6        |

Horizontal Rule

Example

# Common fields title: "Page Title" description: "Meta description for SEO" date: 2024-01-15 lastUpdated: 2024-03-20 author: "Author Name" draft: false # Navigation & organization order: 3 category: "Guides" tags: - mdx - tutorial sidebar_label: "Custom Sidebar Title" slug: "/custom-url-path" # SEO & social keywords: ["mdx", "react", "markdown"] canonical: "https://example.com/page" image: "/og-image.png" noindex: false # Custom data (accessible via frontmatter) difficulty: "intermediate" readingTime: 8 prerequisites: - "Basic React knowledge" - "Markdown familiarity" ---

Accessing Frontmatter

mdx example

---
title: "My Page"
author: "Jane Doe"
---

export const meta = frontmatter;

# {frontmatter.title}

Written by {frontmatter.author}

Import / Export Syntax

Import Patterns

Example

{/* Named imports */} import { Alert, Card, Badge } from '../components'; {/* Default import */} import Layout from '../layouts/DocsLayout'; {/* Rename import */} import { Alert as Warning } from '../components/Alert'; {/* Import everything */} import * as Icons from '../components/icons'; {/* Import non-component (data, utils) */} import { siteConfig } from '../config'; import changelog from '../data/changelog.json'; {/* Dynamic import (for code splitting) */} import dynamic from 'next/dynamic'; const Heavy = dynamic(() => import('../components/Heavy'));

Export Patterns

mdx example

{/* Export metadata */}
export const meta = {
  title: "My Page",
  publishedAt: "2024-01-15"
};

{/* Export functions */}
export function getStaticProps() {
  return { props: { data: fetchData() } };
}

{/* Export constants for use in the document */}
export const version = "3.0.0";

# Release Notes v{version}

{/* Export layout (framework-specific) */}
export { default as Layout } from '../layouts/Docs';

Expression Syntax

Using Expressions in MDX

Curly braces {} let you drop JavaScript expressions anywhere in your content:

Example

{/* Variables */} export const name = "MDX"; export const version = 3; Welcome to {name} version {version}! {/* JavaScript expressions */} Published: {new Date().getFullYear()} Items: {items.length} Status: {isReady ? 'Ready' : 'Loading'} {/* Template literals */} {'Hello, ' + name + '!'} {`Version ${version} released`} {/* Array methods */} {items.map(item => <li key={item.id}>{item.name}</li>)} {/* Conditional rendering */} {showBanner && <Banner />} {user ? <Welcome name={user.name} /> : <LoginPrompt />} {/* Computed values */} {Math.round(percentage * 100)}% {data.filter(d => d.active).length} active items

Expression Limitations

The big gotcha: you can only use *expressions*, not *statements*.

Example

{/* ❌ Statements are NOT allowed */} {if (condition) { return <Alert /> }} {for (let i = 0; i < 5; i++) { ... }} {const x = 5} {/* ✅ Use expressions instead */} {condition && <Alert />} {condition ? <AlertA /> : <AlertB />} {Array.from({length: 5}, (_, i) => <Item key={i} />)}

Common Component Patterns

Callout / Admonition

mdx example

<Callout type="info" title="Note">
  This is informational content.
</Callout>

<Callout type="warning">
  Be careful with this approach.
</Callout>

<Callout type="error" title="Breaking Change">
  This API was removed in v3.0.
</Callout>

Tabs

Example

npm install @mdx-js/react ``` </Tab> <Tab>

Example

yarn add @mdx-js/react ``` </Tab> <Tab>

pnpm add @mdx-js/react

html example

  </Tab>
</Tabs>

Collapsible / Accordion

mdx example

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

  Hidden content with **Markdown** support.

  - List items work
  - Inside details elements
</details>

Steps / Stepper

mdx example

<Steps>
  <Step title="Install dependencies">

npm install @mdx-js/react @mdx-js/mdx

mdx example

  </Step>
  <Step title="Configure bundler">
    Add the MDX plugin to your build config.
  </Step>
  <Step title="Create your first .mdx file">
    Start writing MDX content!
  </Step>
</Steps>

Code with Preview

mdx example

<CodePreview>

<button className="btn btn-primary"> Click me </button>

html example

</CodePreview>

MDX Configuration Quick Reference

Next.js

Example

import createMDX from '@next/mdx'; import remarkGfm from 'remark-gfm'; const withMDX = createMDX({ options: { remarkPlugins: [remarkGfm], rehypePlugins: [], }, }); export default withMDX({ pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'], });

Vite

Example

import { defineConfig } from 'vite'; import mdx from '@mdx-js/rollup'; import remarkGfm from 'remark-gfm'; export default defineConfig({ plugins: [ mdx({ remarkPlugins: [remarkGfm], rehypePlugins: [], }), ], });

Astro

Example

import { defineConfig } from 'astro/config'; import mdx from '@astrojs/mdx'; export default defineConfig({ integrations: [mdx()], markdown: { remarkPlugins: [], rehypePlugins: [], }, });

Key Rules to Remember

These will save you from the most common mistakes:

Rule	Details
One H1 per file	Title comes from the single `#` heading
Close all tags	`<br />` not `<br>`
JSX comments only	`{/* comment */}` not `<!-- comment -->`
Imports at top	After frontmatter, before content
Blank lines matter	Separate components from Markdown with blank lines
Expressions only	No statements (`if`, `for`) inside `{}`
`className` not `class`	React attribute names in JSX
Escape curly braces	Use `{'{'}` or backticks for literal `{`
No `<` in text	Use backticks or `<` for angle brackets
Case-sensitive components	`<alert>` ≠ `<Alert>` (lowercase = HTML)

File Structure Template

When in doubt, structure your MDX file like this:

mdx example

---
title: "Page Title"
description: "Brief description"
---

import { Component } from '../components/Component';

export const metadata = { custom: 'data' };

# Page Title

Introduction paragraph.

## First Section

Content with <Component prop="value">children</Component>.

## Second Section

More content with expressions: {1 + 1}

## Summary

Closing thoughts.

That's the whole MDX syntax in one page. Keep it handy.

Bookmark this. Come back when you forget a syntax. That's what it's here for.

Markdown Syntax Reference

Text Formatting

Syntax	Output	HTML
`bold`	bold	`<strong>`
`italic`	italic	`<em>`
`~~strikethrough~~`	~~strikethrough~~	`<del>`
` inline code `	`inline code`	`<code>`
`link`	link	`<a href>`
`!alt`	Image	`<img>`

Headings

mdx example

# Heading 1        → <h1>
## Heading 2       → <h2>
### Heading 3      → <h3>
#### Heading 4     → <h4>
##### Heading 5    → <h5>
###### Heading 6   → <h6>

Output

Heading 1  (largest, page title)
Heading 2  (section title)
Heading 3  (subsection)
Heading 4  (small section)
Heading 5  (fine detail)
Heading 6  (smallest)

Lists

Example

{/* Unordered */} - Item one - Item two - Nested item - Another nested {/* Ordered */} 1. First 2. Second 3. Third {/* Task list (with GFM plugin) */} - [x] Completed - [ ] Not yet done

Blockquotes

mdx example

> Single line quote

> Multi-line quote
> continues on the next line.
>
> New paragraph in the same quote.

Code Blocks

`mdx example

const x = 42;

Example

function App() { return <h1>Hello</h1>; }

Example

npm install @mdx-js/react

Example

Tables

mdx example

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Cell 1       | Cell 2         | Cell 3        |
| Cell 4       | Cell 5         | Cell 6        |

Horizontal Rule

Example

Accessing Frontmatter

mdx example

---
title: "My Page"
author: "Jane Doe"
---

export const meta = frontmatter;

# {frontmatter.title}

Written by {frontmatter.author}

Import / Export Syntax

Import Patterns

Example

Export Patterns

mdx example

{/* Export metadata */}
export const meta = {
  title: "My Page",
  publishedAt: "2024-01-15"
};

{/* Export functions */}
export function getStaticProps() {
  return { props: { data: fetchData() } };
}

{/* Export constants for use in the document */}
export const version = "3.0.0";

# Release Notes v{version}

{/* Export layout (framework-specific) */}
export { default as Layout } from '../layouts/Docs';

Expression Syntax

Using Expressions in MDX

Curly braces {} let you drop JavaScript expressions anywhere in your content:

Example

Expression Limitations

The big gotcha: you can only use *expressions*, not *statements*.

Example

Common Component Patterns

Callout / Admonition

mdx example

<Callout type="info" title="Note">
  This is informational content.
</Callout>

<Callout type="warning">
  Be careful with this approach.
</Callout>

<Callout type="error" title="Breaking Change">
  This API was removed in v3.0.
</Callout>

Tabs

Example

npm install @mdx-js/react ``` </Tab> <Tab>

Example

yarn add @mdx-js/react ``` </Tab> <Tab>

pnpm add @mdx-js/react

html example

  </Tab>
</Tabs>

Collapsible / Accordion

mdx example

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

  Hidden content with **Markdown** support.

  - List items work
  - Inside details elements
</details>

Steps / Stepper

mdx example

<Steps>
  <Step title="Install dependencies">

npm install @mdx-js/react @mdx-js/mdx

mdx example

  </Step>
  <Step title="Configure bundler">
    Add the MDX plugin to your build config.
  </Step>
  <Step title="Create your first .mdx file">
    Start writing MDX content!
  </Step>
</Steps>

Code with Preview

mdx example

<CodePreview>

<button className="btn btn-primary"> Click me </button>

html example

</CodePreview>

MDX Configuration Quick Reference

Next.js

Example

Vite

Example

Astro

Example

import { defineConfig } from 'astro/config'; import mdx from '@astrojs/mdx'; export default defineConfig({ integrations: [mdx()], markdown: { remarkPlugins: [], rehypePlugins: [], }, });

Key Rules to Remember

These will save you from the most common mistakes:

Rule	Details
One H1 per file	Title comes from the single `#` heading
Close all tags	`<br />` not `<br>`
JSX comments only	`{/* comment */}` not `<!-- comment -->`
Imports at top	After frontmatter, before content
Blank lines matter	Separate components from Markdown with blank lines
Expressions only	No statements (`if`, `for`) inside `{}`
`className` not `class`	React attribute names in JSX
Escape curly braces	Use `{'{'}` or backticks for literal `{`
No `<` in text	Use backticks or `<` for angle brackets
Case-sensitive components	`<alert>` ≠ `<Alert>` (lowercase = HTML)

File Structure Template

When in doubt, structure your MDX file like this:

mdx example

---
title: "Page Title"
description: "Brief description"
---

import { Component } from '../components/Component';

export const metadata = { custom: 'data' };

# Page Title

Introduction paragraph.

## First Section

Content with <Component prop="value">children</Component>.

## Second Section

More content with expressions: {1 + 1}

## Summary

Closing thoughts.

That's the whole MDX syntax in one page. Keep it handy.

Markdown Syntax Reference

Text Formatting

Headings

Lists

Blockquotes

Code Blocks

Tables

Horizontal Rule

Accessing Frontmatter

Import / Export Syntax

Import Patterns

Export Patterns

Expression Syntax

Using Expressions in MDX

Expression Limitations

Common Component Patterns

Callout / Admonition

Tabs

Collapsible / Accordion

Steps / Stepper

Code with Preview

MDX Configuration Quick Reference

Next.js

Vite

Astro

Key Rules to Remember

File Structure Template

Continue learning this concept

Markdown Syntax Reference

Text Formatting

Headings

Lists

Blockquotes

Code Blocks

Tables

Horizontal Rule

Accessing Frontmatter

Import / Export Syntax

Import Patterns

Export Patterns

Expression Syntax

Using Expressions in MDX

Expression Limitations

Common Component Patterns

Callout / Admonition

Tabs

Collapsible / Accordion

Steps / Stepper

Code with Preview

MDX Configuration Quick Reference

Next.js

Vite

Astro

Key Rules to Remember

File Structure Template

Continue learning this concept