Building a Blog with MDX

Why MDX?

When building this blog, I wanted something more powerful than plain Markdown but without the overhead of a full CMS. MDX struck the perfect balance — it lets me write Markdown with the flexibility to embed React components wherever needed.

MDX stands for Markdown + JSX. It compiles Markdown documents to JSX, which means you get all the expressive power of React components mixed seamlessly with readable Markdown prose. This is particularly useful for technical content where you might want to embed interactive examples, custom callouts, or live code snippets.

The Build Pipeline

Getting MDX working required setting up a build pipeline that could compile .mdx files, extract frontmatter, and generate the necessary metadata. The pipeline handles several key steps:

1. Scanning the content directory for .mdx files
2. Parsing frontmatter (title, date, description)
3. Compiling MDX to JavaScript
4. Generating route metadata for navigation

The architecture keeps content completely separate from the application code, making it easy to add new posts without touching the routing layer.

Example: Code Highlighting

One of the great features of MDX is that you can define custom components for Markdown elements. Here's what a code block looks like in this setup:

#!/bin/bash
# Deploy script for the blog
npm run build
npm run format:check
npm run lint
echo "Ready to deploy!"

This simple syntax gets transformed into a beautifully highlighted code block with line numbers and language detection handled automatically by the build pipeline.

Building with MDX has been a smooth experience, and I'm looking forward to creating more technical content that leverages these capabilities.