Markdown and MDX for Content
You'll learn how Markdown and MDX files serve as powerful, developer-friendly content sources for static site generation.
Why Markdown for Static Sites?
Markdown is plain text with simple formatting syntax (headings, lists, links). For static sites, you can store entire pages as .md files in your project, then read and transform them into HTML at build time—the same moment when getStaticProps runs.
Think of Markdown files as a lightweight database: instead of querying a CMS API, your build script reads .md files from a /content folder, parses them, and generates static pages. No external service needed.
What is MDX?
MDX takes Markdown one step further: it lets you embed JSX components directly in your Markdown. Imagine writing a blog post in plain Markdown, then dropping in a custom <Chart> or <Newsletter> component right in the middle of your text.
# My Post
This is regular Markdown text.
<CustomButton onClick={handleClick}>Click me</CustomButton>
More Markdown continues here...
Your build tool (like Next.js with @next/mdx) processes this hybrid format, rendering both Markdown as HTML and React components as interactive elements.
Build-Time Flow
- Place
.mdor.mdxfiles in a/contentdirectory - At build time, read these files (using Node's
fsmodule or a library likegray-matterfor frontmatter metadata) - Parse and transform to HTML/JSX
- Pass content to your page components via
getStaticProps - Generate static HTML pages with full content baked in
This approach combines the simplicity of writing in Markdown with the power of React components and the SEO/performance benefits of SSG.
Key Takeaway:
Markdown and MDX let you author content as files in your repository, which get transformed into static pages at build time—giving you a Git-based, component-friendly content system without needing a separate CMS.