MDX Notes
HubMDX vs Markdown: A Detailed ComparisonWhat is MDX?Why Use MDX? Benefits and Use CasesCreate Your First MDX FileInstalling MDX - Complete Setup GuideMDX Project Structure - Organizing Your Content and ComponentsBlockquotes in MDXCode Blocks in MDXHeadings in MDXImages in MDXLinks in MDXLists in MDXParagraphs in MDXTables in MDXText Formatting in MDXFrontmatter BasicsDocument Metadata in MDXPage Configuration via FrontmatterSEO Fields in FrontmatterBuilding an Accordion/Collapsible ComponentBuilding an Alert/Admonition ComponentBuilding a Card ComponentCreating Custom Components for MDXBuilding a Tabs ComponentInteractive Documentation with MDXMDX LayoutsMDX PluginsPerformance Optimization for MDXReusable Content in MDXSyntax Highlighting in MDXAdmonitions in DocusaurusCode Tabs and CodeBlock in DocusaurusMDX in DocusaurusSidebar Configuration in DocusaurusTabs Component in DocusaurusDocument Versioning in DocusaurusAccessibility in MDXCommon MDX Mistakes and FixesSEO Optimization for MDX ContentMDX Writing Style GuideUsers API - Create UserGetting Started with React in 2024useTheme HookAlex Rivera - Full-Stack Developer & DesignerComplete MDX CheatsheetFurther Reading and MDX ResourcesMDX Interview Questions and AnswersTools for MDX DevelopmentDynamic Content in MDXExporting Variables in MDXImporting Components in MDXJSX Basics in MDXPassing Props in MDXReact Components in MDXMDX Learning RoadmapSetting Up MDX with Next.jsBuilding a Blog with Next.js and MDXCustom Components in Next.js MDXSEO with MDX in Next.js
Every tool you
Here's the tooling that makes MDX development actually pleasant. Editors, linters, formatters, preview tools, frameworks, testing, deployment — the whole stack.
Code Editors and Extensions
VS Code Extensions
VS Code is where most MDX development happens. These extensions make it much better:
MDX (unified)
The official extension. You want this one.
Example
{
"recommendations": [
"unifiedjs.vscode-mdx"
]
}
What you get:
- Syntax highlighting for MDX files
- Embedded JSX highlighting within Markdown
- Frontmatter YAML highlighting
- Support for expressions and imports
Other Extensions Worth Installing
| Extension | Purpose |
|---|---|
unifiedjs.vscode-mdx | MDX syntax highlighting and IntelliSense |
esbenp.prettier-vscode | Auto-formatting MDX files |
dbaeumer.vscode-eslint | Linting integration |
yzhang.markdown-all-in-one | Markdown shortcuts and TOC |
bierner.markdown-mermaid | Mermaid diagram preview |
streetsidesoftware.code-spell-checker | Spell checking in content |
gruntfuggly.todo-tree | Track TODOs in documentation |
redhat.vscode-yaml | Frontmatter YAML validation |
VS Code Settings for MDX
Drop this in your project settings:
Example
{
"[mdx]": {
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true,
"editor.wordWrap": "on",
"editor.quickSuggestions": {
"strings": true
}
},
"files.associations": {
"*.mdx": "mdx"
},
"editor.linkedEditing": true
}
Other Editors
| Editor | MDX Support |
|---|---|
| WebStorm/IntelliJ | Built-in MDX plugin with refactoring |
| Neovim | nvim-treesitter with MDX parser |
| Sublime Text | MDX Syntax Highlighting package |
| Vim | vim-mdx-js plugin |
| Zed | Native MDX support |
Linters
eslint-plugin-mdx
The main linting tool for MDX:
bash example
npm install --save-dev eslint eslint-plugin-mdxExample
import mdx from 'eslint-plugin-mdx';
export default [
{
...mdx.flat,
// Process MDX files
files: ['**/*.mdx'],
processor: mdx.createRemarkProcessor({
lintCodeBlocks: true, // Lint code inside fenced blocks
}),
},
{
...mdx.flatCodeBlocks,
files: ['**/*.mdx/**'], // Code blocks in MDX
rules: {
// Relaxed rules for documentation examples
'no-unused-vars': 'warn',
'no-undef': 'off',
},
},
];
remark-lint
Markdown-level linting for consistent style:
bash example
npm install --save-dev remark-cli remark-lint remark-preset-lint-recommendedExample
export default {
plugins: [
'remark-preset-lint-recommended',
'remark-preset-lint-consistent',
['remark-lint-maximum-line-length', 100],
['remark-lint-maximum-heading-length', 60],
'remark-lint-no-duplicate-headings',
'remark-lint-no-dead-urls',
],
};
markdownlint
Rule-based linting with a config file:
Example
{
"MD013": { "line_length": 120 },
"MD033": false,
"MD041": false,
"MD025": { "front_matter_title": "^\\s*title\\s*[:=]" }
}
Formatters
Prettier
The standard. Set it up once and forget about formatting:
bash example
npm install --save-dev prettierExample
{
"semi": true,
"singleQuote": true,
"trailingComma": "es5",
"tabWidth": 2,
"printWidth": 80,
"proseWrap": "always",
"overrides": [
{
"files": "*.mdx",
"options": {
"parser": "mdx",
"proseWrap": "always"
}
}
]
}
bash example
# Format all MDX files
npx prettier --write "**/*.mdx"
# Check formatting without writing
npx prettier --check "**/*.mdx"EditorConfig
Keeps base formatting consistent regardless of editor:
Example
root = true
[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
[*.mdx]
max_line_length = 100
trim_trailing_whitespace = true
Preview and Development Tools
MDX Playground
The quickest way to test MDX syntax without setting anything up:
- URL: mdxjs.com/playground
- Features: Real-time compilation, AST viewer, error display
- Use for: Quick syntax testing, debugging compilation issues
Storybook
Great for previewing your MDX components in isolation:
bash example
npm install --save-dev @storybook/addon-docsExample
export default {
stories: ['../docs/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
addons: ['@storybook/addon-docs'],
};
mdx title="docs/Button.mdx" example
import { Meta, Canvas, Story } from '@storybook/blocks';
import { Button } from '../src/components/Button';
<Meta title="Components/Button" component={Button} />
# Button Component
<Canvas>
<Story name="Primary">
<Button variant="primary">Click me</Button>
</Story>
</Canvas>Local Preview Servers
| Tool | Command | Best For |
|---|---|---|
| Next.js dev | next dev | Next.js MDX projects |
| Astro dev | astro dev | Astro MDX projects |
| Docusaurus | docusaurus start | Documentation sites |
| Vite | vite dev | Vite-based projects |
Documentation Frameworks
Docusaurus
Facebook's doc framework. Mature, feature-rich, great MDX support:
bash example
npx create-docusaurus@latest my-docs classicGets you: Versioning, search, i18n, MDX plugins, sidebar generation
Nextra
Lightweight docs on top of Next.js:
bash example
npm install nextra nextra-theme-docsGets you: File-based routing, full-text search, dark mode, MDX components
Astro Starlight
Fast builds, accessibility-first:
bash example
npm create astro@latest -- --template starlightGets you: Fast builds, i18n, accessibility, component islands
Which One to Pick?
| Framework | Build Speed | Customization | Learning Curve | Best For |
|---|---|---|---|---|
| Docusaurus | Medium | High | Medium | Large docs sites |
| Nextra | Fast | Medium | Low | Simple docs |
| Starlight | Very Fast | High | Low | Performance-first |
| Mintlify | N/A (hosted) | Medium | Very Low | API docs |
| GitBook | N/A (hosted) | Low | Very Low | Quick setup |
Component Libraries
Documentation-Specific Components
bash example
# Fumadocs UI - components for documentation
npm install fumadocs-ui
# Shadcn/ui - customizable component library
npx shadcn-ui@latest initGood Component Libraries for MDX Sites
| Library | Type | Use Case |
|---|---|---|
| shadcn/ui | Copy-paste components | Custom docs sites |
| Radix UI | Headless primitives | Accessible components |
| Fumadocs UI | Doc-specific | Tabs, callouts, cards |
| Chakra UI | Styled components | Rapid development |
| Tailwind CSS | Utility classes | Custom styling |
Testing Tools
Content Testing
bash example
# Link validation
npm install --save-dev remark-validate-links
# Spell checking
npm install --save-dev cspell
# Writing style (technical writing rules)
npm install --save-dev alex # Catches insensitive language
npm install --save-dev write-good # Style suggestionsjson title="package.json" example
{
"scripts": {
"test:links": "remark --use validate-links docs/",
"test:spelling": "cspell \"docs/**/*.mdx\"",
"test:language": "alex docs/",
"test:style": "write-good docs/**/*.mdx"
}
}Visual Regression Testing
Catch unintended layout changes:
Example
import { test, expect } from '@playwright/test';
test('documentation page visual snapshot', async ({ page }) => {
await page.goto('/docs/getting-started');
await expect(page).toHaveScreenshot('getting-started.png');
});
Accessibility Testing
bash example
npm install --save-dev @axe-core/playwrightExample
import AxeBuilder from '@axe-core/playwright';
test('docs page has no a11y violations', async ({ page }) => {
await page.goto('/docs/guide');
const results = await new AxeBuilder({ page }).analyze();
expect(results.violations).toEqual([]);
});
Deployment Platforms
Static Hosting (Best for MDX Sites)
| Platform | Free Tier | Build Support | Best Feature |
|---|---|---|---|
| Vercel | Yes | Next.js native | Preview deployments |
| Netlify | Yes | All frameworks | Branch deploys |
| Cloudflare Pages | Yes | Fast global CDN | Edge rendering |
| GitHub Pages | Yes | GitHub Actions | Free for OSS |
| AWS Amplify | Free tier | All frameworks | AWS integration |
Deployment Configuration
Example
name: Deploy Documentation
on:
push:
branches: [main]
paths: ['docs/**', 'src/components/**']
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'
- run: npm ci
- run: npm run build
- uses: actions/upload-pages-artifact@v3
with:
path: ./out
CI/CD Tools
Automated Quality Checks
Run these on every PR to catch issues before they hit production:
Example
name: Documentation CI
on: [pull_request]
jobs:
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- name: Lint MDX
run: npx eslint "docs/**/*.mdx"
- name: Check formatting
run: npx prettier --check "docs/**/*.mdx"
- name: Spell check
run: npx cspell "docs/**/*.mdx"
- name: Validate links
run: npx remark --use validate-links docs/
- name: Build test
run: npm run build
- name: Accessibility audit
run: npm run test:a11y
Pre-commit Hooks
Catch problems before they even get committed:
bash example
npm install --save-dev husky lint-stagedExample
{
"lint-staged": {
"*.mdx": [
"prettier --write",
"eslint --fix",
"cspell --no-must-find-files"
]
}
}
Build and Bundling Tools
| Tool | Integration | Purpose |
|---|---|---|
@mdx-js/rollup | Vite, Rollup | Compile MDX in Rollup/Vite |
@mdx-js/loader | Webpack | Compile MDX in Webpack |
@mdx-js/esbuild | esbuild | Fast MDX compilation |
@next/mdx | Next.js | Next.js MDX integration |
@astrojs/mdx | Astro | Astro MDX integration |
gatsby-plugin-mdx | Gatsby | Gatsby MDX integration |
Summary
Start with VS Code + the MDX extension + Prettier. That gets you productive immediately. Add linting, testing, and CI/CD as your project grows. Pick a documentation framework that matches your team's skills and how big your site needs to be.
Exam Focus
Revise definitions, diagrams, examples, and short-answer points for Tools for MDX Development.
Interview Use
Prepare one clear explanation, one practical example, and one common mistake for this MDX Tutorial topic.
Search Terms
mdx-tutorial, mdx tutorial, mdx, tutorial, resources, useful, tools, tools for mdx development
Related MDX Tutorial Topics
Continue learning this concept
ResourcesComplete MDX CheatsheetEverything you need to look up about MDX syntax — Markdown basics, JSX patterns, frontmatter, imports/exports, and expressions — all on one page.ResourcesFurther Reading and MDX ResourcesThe best links for learning MDX — official docs, tutorials, YouTube channels, courses, open source examples, and community spots.ResourcesMDX Interview Questions and Answers30+ MDX interview questions — from basic syntax to compiler internals — with answers and code examples you can actually use to prep.AdvancedInteractive Documentation with MDXMake your docs do things. Live code playgrounds, editable examples, quizzes, step-by-step tutorials — all built with React components inside MDX.AdvancedMDX LayoutsWrap your MDX pages in consistent shells — headers, sidebars, footers. Learn how to build, nest, and conditionally swap layouts based on frontmatter.AdvancedMDX PluginsAdd superpowers to your MDX with remark and rehype plugins — tables, math, syntax highlighting, auto-linked headings. Plus how to write your own.