MDX Writing Style Guide

Knowing MDX syntax is the easy part. Writing docs that people actually want to read? That takes a system. This guide covers the rules for keeping your MDX content consistent, scannable, and maintainable.

Documentation-as-Code Philosophy

Treat your docs like code. Seriously.

Version control — All MDX files live in Git alongside source code
Code review — Docs go through pull requests just like features
Testing — Validate links, code examples, and build output
Continuous deployment — Docs deploy automatically on merge
Single source of truth — Don't duplicate content across files

Example

// Your docs should be part of the same repository project/ ├── src/ │ └── components/ ├── docs/ │ ├── getting-started.mdx │ ├── api-reference.mdx │ └── guides/ ├── package.json └── README.md

Consistent Heading Hierarchy

Headings are the skeleton of your document. Mess them up and everything feels disorganized.

Rules for Headings

One H1 per file — The H1 is your page title; never use more than one
Never skip levels — Go from H2 to H3, never H2 to H4
Use sentence case — Write "Getting started with MDX" not "Getting Started With MDX"
Be descriptive — "Configuring the MDX compiler" beats "Configuration"
Keep them concise — Aim for 3–8 words per heading

mdx example

# Page Title (H1 - only one per file)

## Major Section (H2)

### Subsection (H3)

#### Detail Point (H4 - use sparingly)

{/* ❌ DON'T skip heading levels */}
# Title
#### This skips H2 and H3 - Bad!

{/* ✅ DO maintain proper hierarchy */}
# Title
## Section
### Subsection
#### Detail

Your headings generate the table of contents. Each H2 and H3 should make sense on its own as a nav item. If someone scans just the headings, they should understand the page structure.

Paragraph Length and Readability

Walls of text are death. Break things up.

Paragraphs: 2–4 sentences maximum
Sentences: 15–25 words on average
Line length: Break lines at ~80 characters in source (makes diffs cleaner)
Scannability: Use bold for key terms, lists for sequences, and callouts for warnings

mdx example

{/* ❌ Too dense */}
MDX combines Markdown and JSX to create powerful documentation. It allows you to import
components and use them inline with your Markdown content. This means you can create
interactive examples, custom callouts, and dynamic content that goes far beyond what
traditional Markdown offers. The compilation process transforms your MDX files into
React components that can be rendered in any React application.

{/* ✅ Better: broken into digestible chunks */}
MDX combines Markdown and JSX to create powerful documentation. It allows you to
import components and use them inline with your Markdown content.

This means you can create interactive examples, custom callouts, and dynamic content
that goes far beyond traditional Markdown.

The compilation process transforms your MDX files into React components that can be
rendered in any React application.

Code Example Quality

Code examples are the reason people are reading your docs. Make them good.

Guidelines for Code Blocks

mdx example

{/* Always specify the language for syntax highlighting */}

const greeting = "Hello, MDX!";

{/* Add titles to provide context */}

export function Alert({ type, children }) { return <div className={alert alert-${type}}>{children}</div>; }

{/* Show complete, runnable examples when possible */}

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

My Page

ℹ️ Info: This is a complete, working example that readers can copy and use.

Example

Code Example Checklist

✅ Language identifier specified
✅ Title/filename when relevant
✅ Complete and runnable (no missing imports)
✅ Comments explain the "why," not the "what"
✅ Realistic variable names (not foo, bar)
✅ Error handling included where appropriate
✅ Output shown when helpful

Component Usage Guidelines

When you drop custom components into MDX, keep things consistent:

mdx example

import { Callout } from '../components/Callout';
import { CodeExample } from '../components/CodeExample';
import { TabGroup, Tab } from '../components/Tabs';

{/* Group all imports at the top, after frontmatter */}

{/* Use components to enhance, not replace, standard content */}
<Callout type="warning" title="Breaking Change">
  Version 3.0 removes support for the legacy `mdxType` prop.
  Migrate your components before upgrading.
</Callout>

{/* Prefer composition over complex props */}
<TabGroup>
  <Tab label="npm">

npm install @mdx-js/react ``` </Tab> <Tab label="yarn">

Example

yarn add @mdx-js/react

</Tab> </TabGroup>

Scenario	Use
Simple text formatting	Markdown
Static code blocks	Markdown fenced blocks
Interactive examples	Custom component
Warnings/notes	Callout component
Tabbed content	Tab component
Data tables	Markdown tables or Table component
Navigation elements	Custom component

docs/ ├── getting-started.mdx ✅ kebab-case ├── api-reference.mdx ✅ descriptive ├── GettingStarted.mdx ❌ PascalCase (for components only) ├── getting_started.mdx ❌ snake_case ├── 01-introduction.mdx ✅ numbered for ordered content ├── 02-installation.mdx ✅ consistent numbering └── components/ ├── Button.mdx ✅ PascalCase matches component name └── DataTable.mdx ✅ matches the component

1. Use kebab-case for documentation files	`writing-guidelines.mdx`
3. Use numeric prefixes for ordered sequences	`01-setup.mdx`, `02-config.mdx`
4. Keep names short but descriptive	prefer `auth-setup.mdx` over `a.mdx`

docs/ ├── index.mdx # Landing page ├── getting-started/ │ ├── index.mdx # Section overview │ ├── installation.mdx │ ├── first-document.mdx │ └── project-structure.mdx ├── guides/ │ ├── components.mdx │ ├── styling.mdx │ └── deployment.mdx ├── api/ │ ├── compiler-options.mdx │ └── plugins.mdx └── resources/ ├── cheatsheet.mdx └── faq.mdx

Example

### Organization Principles - **Progressive disclosure** — Start simple, add complexity gradually - **Task-oriented** — Organize by what users want to accomplish - **Consistent depth** — Don't nest deeper than 3 levels - **Clear entry points** — Every section has an index/overview page ## Review Checklist Run through this before merging any MDX content: ### Content Quality - [ ] Accurate and up-to-date information - [ ] No broken links (internal or external) - [ ] All code examples tested and working - [ ] Consistent terminology throughout - [ ] No typos or grammatical errors ### Structure - [ ] Proper heading hierarchy (no skipped levels) - [ ] Frontmatter complete and valid - [ ] Imports at the top of the file - [ ] Logical content flow ### Technical - [ ] MDX compiles without errors - [ ] Components render correctly - [ ] Images have alt text - [ ] File follows naming conventions - [ ] No unused imports ### Accessibility - [ ] Semantic heading structure - [ ] Descriptive link text (no "click here") - [ ] Code examples have language identifiers - [ ] Tables have headers ## Summary Good MDX docs are consistent, scannable, and written for the reader — not for you. Follow these guidelines and your content stays maintainable as it grows. Treat your docs as first-class citizens. They deserve the same care as your source code.

Documentation-as-Code Philosophy

Treat your docs like code. Seriously.

Version control — All MDX files live in Git alongside source code
Code review — Docs go through pull requests just like features
Testing — Validate links, code examples, and build output
Continuous deployment — Docs deploy automatically on merge
Single source of truth — Don't duplicate content across files

Example

Consistent Heading Hierarchy

Headings are the skeleton of your document. Mess them up and everything feels disorganized.

Rules for Headings

One H1 per file — The H1 is your page title; never use more than one
Never skip levels — Go from H2 to H3, never H2 to H4
Use sentence case — Write "Getting started with MDX" not "Getting Started With MDX"
Be descriptive — "Configuring the MDX compiler" beats "Configuration"
Keep them concise — Aim for 3–8 words per heading

mdx example

# Page Title (H1 - only one per file)

## Major Section (H2)

### Subsection (H3)

#### Detail Point (H4 - use sparingly)

{/* ❌ DON'T skip heading levels */}
# Title
#### This skips H2 and H3 - Bad!

{/* ✅ DO maintain proper hierarchy */}
# Title
## Section
### Subsection
#### Detail

Your headings generate the table of contents. Each H2 and H3 should make sense on its own as a nav item. If someone scans just the headings, they should understand the page structure.

Paragraph Length and Readability

Walls of text are death. Break things up.

Paragraphs: 2–4 sentences maximum
Sentences: 15–25 words on average
Line length: Break lines at ~80 characters in source (makes diffs cleaner)
Scannability: Use bold for key terms, lists for sequences, and callouts for warnings

mdx example

{/* ❌ Too dense */}
MDX combines Markdown and JSX to create powerful documentation. It allows you to import
components and use them inline with your Markdown content. This means you can create
interactive examples, custom callouts, and dynamic content that goes far beyond what
traditional Markdown offers. The compilation process transforms your MDX files into
React components that can be rendered in any React application.

{/* ✅ Better: broken into digestible chunks */}
MDX combines Markdown and JSX to create powerful documentation. It allows you to
import components and use them inline with your Markdown content.

This means you can create interactive examples, custom callouts, and dynamic content
that goes far beyond traditional Markdown.

The compilation process transforms your MDX files into React components that can be
rendered in any React application.

Code Example Quality

Code examples are the reason people are reading your docs. Make them good.

Guidelines for Code Blocks

mdx example

{/* Always specify the language for syntax highlighting */}

const greeting = "Hello, MDX!";

{/* Add titles to provide context */}

export function Alert({ type, children }) { return <div className={alert alert-${type}}>{children}</div>; }

{/* Show complete, runnable examples when possible */}

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

My Page

ℹ️ Info: This is a complete, working example that readers can copy and use.

Example

Code Example Checklist

✅ Language identifier specified
✅ Title/filename when relevant
✅ Complete and runnable (no missing imports)
✅ Comments explain the "why," not the "what"
✅ Realistic variable names (not foo, bar)
✅ Error handling included where appropriate
✅ Output shown when helpful

Component Usage Guidelines

When you drop custom components into MDX, keep things consistent:

mdx example

import { Callout } from '../components/Callout';
import { CodeExample } from '../components/CodeExample';
import { TabGroup, Tab } from '../components/Tabs';

{/* Group all imports at the top, after frontmatter */}

{/* Use components to enhance, not replace, standard content */}
<Callout type="warning" title="Breaking Change">
  Version 3.0 removes support for the legacy `mdxType` prop.
  Migrate your components before upgrading.
</Callout>

{/* Prefer composition over complex props */}
<TabGroup>
  <Tab label="npm">

npm install @mdx-js/react ``` </Tab> <Tab label="yarn">

Example

yarn add @mdx-js/react

</Tab> </TabGroup>

Scenario	Use
Simple text formatting	Markdown
Static code blocks	Markdown fenced blocks
Interactive examples	Custom component
Warnings/notes	Callout component
Tabbed content	Tab component
Data tables	Markdown tables or Table component
Navigation elements	Custom component

1. Use kebab-case for documentation files	`writing-guidelines.mdx`
3. Use numeric prefixes for ordered sequences	`01-setup.mdx`, `02-config.mdx`
4. Keep names short but descriptive	prefer `auth-setup.mdx` over `a.mdx`

Example

MDX Writing Style Guide

Documentation-as-Code Philosophy

Consistent Heading Hierarchy

Rules for Headings

Heading as Navigation

Paragraph Length and Readability

Code Example Quality

Guidelines for Code Blocks

My Page

Code Example Checklist

Component Usage Guidelines

Continue learning this concept

MDX Writing Style Guide

Documentation-as-Code Philosophy

Consistent Heading Hierarchy

Rules for Headings

Heading as Navigation

Paragraph Length and Readability

Code Example Quality

Guidelines for Code Blocks

My Page

Code Example Checklist

Component Usage Guidelines

Continue learning this concept