How I Structure a Next.js and MDX Personal Blog

TL;DR

This blog uses a simple content-first structure: MDX files live in content/posts, Next.js reads frontmatter, and the UI builds article pages, category pages, tag pages, and related posts from the same source.

Why MDX Works Well for a Personal Blog

MDX keeps writing close to the codebase without turning every article into a CMS task. I can write normal Markdown, add structured frontmatter, and still use custom components when a post needs a callout or embedded media.

For a personal technical blog, that tradeoff feels right. The content stays portable, searchable, and reviewable in Git.

The Content Model

Each post contains frontmatter like this:

title: "Building Calm Backend Systems"
description: "A practical checklist for production services."
date: "2026-06-19"
category: "Backend"
tags:
  - Backend
  - Observability
coverImage: "/images/covers/building-calm-backend-systems.svg"

The app parses that metadata and creates a normalized post object with a slug, category slug, tag slugs, reading time, related posts, and headings for the table of contents.

Pages Generated From One Source

The same post files power several surfaces:

Home page cards.
Blog archive.
Category pages.
Tag pages.
Blog detail pages.
Related article lists.
RSS and sitemap output.

This keeps the system small. When a new MDX file lands, the rest of the blog can update automatically.

Design Notes

I want the site to feel like a personal tech desk, not a corporate marketing page. The dark theme, compact cards, and soft borders are there to make the content feel focused without becoming sterile.

The layout is dense enough to browse, but the article page still gives the writing room to breathe.

Conclusion

Next.js and MDX are a strong fit when the blog is part writing space, part engineering project. The architecture stays understandable, and the content remains easy to own.