Building a Modern Blog with Next.js and MDX

Introduction

Building a blog that's both developer-friendly and performant has always been a challenge. With Next.js and MDX, we can create a blogging system that allows us to write in Markdown while embedding React components directly in our posts.

In this guide, we'll walk through the complete setup of a modern blog system that includes:

Syntax-highlighted code blocks
Custom React components
GitHub Flavored Markdown support
Static site generation for maximum performance

Setting Up the Project

First, let's install the necessary dependencies:

bash

1bun add gray-matter reading-time next-mdx-remote rehype-pretty-code shiki remark-gfm

Project Structure

Here's how we'll organize our blog content:

1content/
2  blog/
3    my-first-post.mdx
4    another-post.mdx
5lib/
6  blog.ts
7  mdx-renderer.tsx
8app/
9  blogs/
10    [slug]/
11      page.tsx

Writing MDX Content

MDX lets you use JSX in your markdown content. You can import components, and even write them inline. Here's an example:

Why MDX?

MDX combines the simplicity of Markdown with the power of React components, making it perfect for technical blog posts that need interactive elements.

Code Blocks with Syntax Highlighting

Code blocks are automatically syntax-highlighted using Shiki. Here's an example:

typescript

1interface BlogPost {
2  slug: string;
3  title: string;
4  description: string;
5  date: string;
6  tags: string[];
7}
8
9function getAllPosts(): BlogPost[] {
10  const files = fs.readdirSync(BLOG_DIR);
11  return files
12    .filter((file) => file.endsWith(".mdx"))
13    .map((file) => parsePost(file))
14    .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
15}

Tables

Tables are supported through GitHub Flavored Markdown:

Feature	Status	Notes
Syntax Highlighting	Yes	Powered by Shiki
Copy Button	Yes	One-click code copying
Dark/Light Theme	Yes	Automatic theme switching
Custom Components	Yes	MDX component embedding

You can use the Callout component with different types: info, warning, danger, tip, and success.

Performance Considerations

When building a blog with Next.js, keep these tips in mind:

Use Static Generation — Blog posts rarely change, so use generateStaticParams to build pages at compile time.
Optimize Images — Use next/image for automatic image optimization.
Minimize Client JavaScript — Keep your MDX components server-rendered when possible.

"The best code is the code that doesn't need to run on the client." — A wise developer

Conclusion

With this setup, you have a powerful blogging system that's:

Fast — Statically generated pages
Flexible — Embed any React component
Developer-friendly — Write in Markdown
Beautiful — Syntax highlighting and custom styling

Happy blogging.

ALENTINE