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
The best links for learning MDX — official docs, tutorials, YouTube channels, courses, open source examples, and community spots.
Here's everything worth bookmarking if you're serious about MDX. Official docs, good tutorials, YouTube channels that actually explain things, and community hangouts where you can get help.
Official Documentation
Core MDX Resources
| Resource | URL | Description |
|---|---|---|
| MDX Official Docs | mdxjs.com | The definitive guide to MDX syntax, APIs, and configuration |
| MDX Playground | mdxjs.com/playground | Interactive online editor for testing MDX |
| MDX GitHub | github.com/mdx-js/mdx | Source code, issues, and discussions |
| unified Ecosystem | unifiedjs.com | The broader ecosystem MDX is built on |
Related Specifications
| Resource | Description |
|---|---|
| CommonMark Spec | The Markdown standard MDX extends |
| GFM Spec | GitHub Flavored Markdown specification |
| MDX Specification | Formal MDX language specification |
| React JSX Docs | JSX syntax reference |
Tutorials and Guides
Getting Started
- MDX Getting Started Guide — Official step-by-step setup for all major frameworks
- Next.js MDX Documentation — Next.js-specific MDX integration
- Astro MDX Guide — Using MDX with Astro
- Gatsby MDX Guide — Gatsby's MDX plugin docs
- Docusaurus MDX Guide — Using React in Docusaurus Markdown
Intermediate Stuff
- Building a Blog with MDX and Next.js — Full blog implementation
- Creating Custom MDX Components — Building and providing components
- MDX Plugin Development — Writing remark/rehype plugins
- Content Collections with MDX — Astro's typed content approach
Advanced Topics
- MDX Compiler Internals — How the compiler works under the hood
- AST Explorer for MDX — Visualize MDX abstract syntax trees
- Performance Optimization for MDX Sites — Rendering strategies for content sites
- Unified Plugin Guide — Creating custom AST transformations
Blog Posts and Articles
Essential Reads
| Title | Author | Topic |
|---|---|---|
| "MDX 3: What's New" | MDX Team | Major version changes and migration |
| "Why MDX?" | Compositor | The philosophy behind MDX |
| "Building Design System Docs with MDX" | Josh Comeau | Practical MDX for design systems |
| "The Case for MDX" | Chris Biscardi | Why MDX over alternatives |
| "Content Driven Sites with MDX" | Lee Robinson | Architecture patterns |
| "From Markdown to MDX" | Kent C. Dodds | Migration strategies |
Worth a Deep Dive
- "How MDX Transforms Your Content" — The compilation pipeline from source to React components
- "Remark and Rehype: The Unified Ecosystem" — Deep dive into the plugin architecture powering MDX
- "Static Site Generation Patterns for Content" — Comparing approaches for content-heavy sites
- "Type-Safe MDX with TypeScript" — Adding full type safety to your MDX workflow
- "MDX and React Server Components" — The future of MDX in the RSC world
YouTube Channels and Videos
Channels Worth Subscribing To
| Channel | Focus | Content Type |
|---|---|---|
| Fireship | Quick overviews | "MDX in 100 Seconds" |
| Lee Robinson | Next.js + MDX | Tutorials, architecture |
| James Q Quick | Web development | MDX project builds |
| Traversy Media | Web tutorials | Framework tutorials |
| Jack Herrington | React patterns | Advanced component design |
| Theo Browne | Web opinions | Tool comparisons |
| Web Dev Simplified | Fundamentals | Markdown/MDX basics |
Must-Watch Videos
- "MDX in 100 Seconds" — Fireship's quick intro to MDX
- "Build a Modern Blog with Next.js 14 and MDX" — Full project walkthrough
- "The Ultimate Documentation Stack" — Comparing Docusaurus, Nextra, and Starlight
- "React Server Components and MDX" — Future of content rendering
- "Writing Custom Remark Plugins" — Step-by-step plugin development
Online Courses
Free Courses
| Course | Platform | Level |
|---|---|---|
| MDX Official Tutorial | mdxjs.com | Beginner |
| Next.js Learn (Content section) | nextjs.org | Beginner-Intermediate |
| Astro Documentation Tutorial | docs.astro.build | Beginner |
| Docusaurus Tutorial | docusaurus.io | Beginner |
Paid Courses
| Course | Platform | Level | Price Range |
|---|---|---|---|
| "Building Documentation Sites" | Egghead.io | Intermediate | $$ |
| "Content Layer with Next.js" | Frontend Masters | Advanced | $$ |
| "Technical Writing for Developers" | Udemy | Beginner | $ |
| "Full Stack Documentation" | Pluralsight | Intermediate | $$ |
| "React Component Libraries" | Level Up Tutorials | Intermediate | $ |
Suggested Learning Path
mdx example
{/* Suggested learning progression */}
## Beginner Path (2-4 weeks)
1. Learn Markdown basics → CommonMark tutorial
2. Understand React/JSX → React official tutorial
3. Set up your first MDX project → MDX Getting Started
4. Build a simple blog → Next.js + MDX tutorial
## Intermediate Path (4-8 weeks)
1. Custom components → MDXProvider and component mapping
2. Plugins → remark-gfm, rehype-highlight, custom plugins
3. Framework mastery → Deep dive into your chosen framework
4. Testing and CI/CD → Automated quality pipelines
## Advanced Path (8-12 weeks)
1. Compiler internals → Study @mdx-js/mdx source
2. Custom integrations → Build your own MDX loader
3. Performance at scale → Large docs site optimization
4. Contributing → Submit PRs to MDX ecosystem packagesOpen Source Projects Using MDX
Documentation Sites (Great Examples to Study)
| Project | Framework | Notable Feature |
|---|---|---|
| React Docs | Next.js | Interactive examples |
| Next.js Docs | Next.js | Version-aware content |
| Tailwind CSS Docs | Next.js | Live previews |
| Vercel Docs | Next.js | Multi-product docs |
| Chakra UI Docs | Next.js | Component playground |
| Radix Docs | Next.js | Accessibility-first |
| Astro Docs | Astro/Starlight | i18n, fast builds |
Starter Templates
Grab one and start building:
bash example
# Nextra documentation starter
npx create-next-app --example https://github.com/shuding/nextra-docs-template
# Docusaurus starter
npx create-docusaurus@latest my-docs classic
# Astro Starlight
npm create astro@latest -- --template starlight
# MDX blog starter
npx create-next-app --example blog-starterComponent Libraries with MDX Docs
- shadcn/ui — Component library documented entirely in MDX
- Fumadocs — Documentation framework with MDX
- Contentlayer — Type-safe content SDK for MDX
- Velite — Content build tool supporting MDX
- mdx-bundler — Compile and bundle MDX files
Community
Where to Get Help
| Platform | Link | Best For |
|---|---|---|
| MDX GitHub Discussions | github.com/mdx-js/mdx/discussions | Technical questions |
| unified Discord | discord.gg/unified | Real-time help |
| Reddit r/reactjs | reddit.com/r/reactjs | General React/MDX |
| Dev.to #mdx | dev.to/t/mdx | Articles and discussions |
| Stack Overflow | stackoverflow.com/questions/tagged/mdx | Q&A |
Social Media
- Twitter/X: Follow
@mdikidarko(MDX),@unaborned(unified), framework maintainers - Mastodon: The unified community is active in the Fediverse
- LinkedIn: Search "MDX" or "documentation engineering" for professional discussions
Contributing to MDX
Want to give back? Here's how to get started:
bash example
# 1. Fork and clone the MDX repository
git clone https://github.com/YOUR-USERNAME/mdx.git
cd mdx
# 2. Install dependencies
npm install
# 3. Run tests
npm test
# 4. Find "good first issue" labels
# https://github.com/mdx-js/mdx/labels/good%20first%20issue
# 5. Areas where contributions are welcome:
# - Documentation improvements
# - Bug fixes
# - Plugin development
# - Test coverage
# - TypeScript typesConferences and Events
Relevant Conferences
| Conference | Focus | MDX Relevance |
|---|---|---|
| React Conf | React ecosystem | MDX tooling, RSC integration |
| Next.js Conf | Next.js | Content layer, MDX features |
| ViteConf | Vite ecosystem | MDX plugin development |
| Write the Docs | Documentation | Technical writing with MDX |
| Jamstack Conf | Static sites | MDX-powered content |
| React Summit | React advanced | Component architecture |
Meetups
- Write the Docs Meetups — Local chapters worldwide for documentation professionals
- React Meetups — Local React groups often cover MDX
- Jamstack Meetups — Content-focused web development
Newsletters
Stay in the Loop
| Newsletter | Frequency | Focus |
|---|---|---|
| This Week in React | Weekly | React ecosystem including MDX |
| Bytes.dev | Weekly | JavaScript/web dev tools |
| Frontend Focus | Weekly | Frontend development news |
| Docusaurus Blog | Monthly | Docusaurus/MDX updates |
| Astro Newsletter | Monthly | Astro/MDX content |
| Smashing Magazine | Weekly | Web development articles |
RSS Feeds to Follow
Example
<!-- Add these to your RSS reader -->
https://mdxjs.com/blog/feed.xml
https://unifiedjs.com/blog/feed.xml
https://nextjs.org/feed.xml
https://astro.build/rss.xml
Books
Recommended Reading
| Book | Author | Why Read It |
|---|---|---|
| "Docs for Developers" | Jared Bhatt & Zachary Sarah Corleissen | Documentation strategy |
| "The Good Parts of Technical Writing" | Various | Writing quality |
| "Design Systems" | Alla Kholmatova | Component design philosophy |
| "Don't Make Me Think" | Steve Krug | UX for documentation |
| "A Philosophy of Software Design" | John Ousterhout | Clean abstractions |
Quick Reference Links
Bookmark These
Example
{/* Essential daily-use links */}
- 📖 [MDX Docs](https://mdxjs.com) — Syntax reference
- 🎮 [MDX Playground](https://mdxjs.com/playground/) — Test syntax
- 📦 [npm: @mdx-js](https://www.npmjs.com/org/mdx-js) — All MDX packages
- 🐛 [MDX Issues](https://github.com/mdx-js/mdx/issues) — Report bugs
- 💬 [MDX Discussions](https://github.com/mdx-js/mdx/discussions) — Ask questions
- 🌳 [AST Explorer](https://astexplorer.net/) — Visualize ASTs
- 🔌 [Unified Plugins](https://unifiedjs.com/explore/) — Find plugins
- 📝 [CommonMark Spec](https://spec.commonmark.org/) — Markdown rules
Summary
Start with the official docs, pick a framework, join a community, and build something. The best way to learn MDX is to ship a project. Start small, iterate, and share what you make.
Continue the lesson path
Study next in this module
01ResourcesComplete MDX CheatsheetEverything you need to look up about MDX syntax — Markdown basics, JSX patterns, frontmatter, imports/exports, and expressions — all on one page.02ResourcesMDX Interview Questions and Answers30+ MDX interview questions — from basic syntax to compiler internals — with answers and code examples you can actually use to prep.03ResourcesTools for MDX DevelopmentEvery tool you04AdvancedInteractive Documentation with MDXMake your docs do things. Live code playgrounds, editable examples, quizzes, step-by-step tutorials — all built with React components inside MDX.