Next.js with MDX Project Structure
MDX integration for blogs, docs, and content-driven sites with frontmatter.
Project Directory
my-blog/
app/
layout.tsx
page.tsx
globals.css
blog/
page.tsx
Blog index
[slug]/
page.tsx
Renders MDX post
docs/
Documentation section
page.tsx
[[...slug]]/
Catch-all for nested docs
page.tsx
content/
MDX content files
blog/
hello-world.mdx
getting-started.mdx
docs/
index.mdx
installation.mdx
guides/
quick-start.mdx
lib/
mdx.ts
MDX utilities and helpers
content.ts
Content fetching functions
components/
mdx/
Custom MDX components
index.tsx
Component map
callout.tsx
code-block.tsx
blog/
post-card.tsx
post-header.tsx
contentlayer.config.ts
Or next-mdx-remote config
next.config.js
package.json
tsconfig.json
.gitignore
Why This Structure?
MDX lets you use React components inside Markdown—perfect for blogs and docs. Content lives in content/ as .mdx files with frontmatter. Use Contentlayer or next-mdx-remote to parse MDX and generate type-safe content. Custom components in components/mdx/ override default elements.
Key Directories
- content/-All MDX files organized by content type
- content/blog/-Blog posts with frontmatter
- content/docs/-Documentation with nested structure
- components/mdx/-Custom MDX component overrides
- lib/content.ts-Functions to fetch and filter content
MDX Frontmatter
---
title: "Hello World"
date: "2024-01-15"
description: "My first post"
---
# Hello World
Custom components work in MDX!
When To Use This
- Developer blogs and personal sites
- Product documentation sites
- Content-heavy marketing sites
- Projects mixing Markdown with React
Trade-offs
- Build complexity-MDX processing adds build steps
- Library choice-Contentlayer vs next-mdx-remote vs @next/mdx
- No CMS-Content is file-based, not editable by non-devs