Complete MDX Cheatsheet

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.