Build Your Own Minimal MDX Blog
Most developer blogs suffer from one of two extremes: either they are hooked up to a bloated, over-engineered headless CMS, or they are bare-bones templates that require hacking twenty different CSS and config files just to change your accent color or add a social link.
When I rebuilt this blog, I wanted something different:
- Blazing fast: Next.js 16 App Router with zero client-side bloat.
- Pure Markdown & MDX: Write posts in plain
.mdfiles with rich code snippets and diagrams. - Single config file: Every color, title, author handle, and link controlled in one spot (
src/blog.config.ts). - Built-in printable resume: A dedicated
/resumepage with clean print-to-PDF formatting out of the box.
To make this effortless for anyone else who just wants a clean corner of the internet to write their thoughts, I packaged the entire setup into an open-source CLI: create-mdx-blog.
Here is how you can have your own blog up and running in a couple of minutes.
1. Scaffold your blog
You don't need to clone repos or fiddle with boilerplate. Open your terminal and run:
npx create-mdx-blog my-blog(Or use pnpm create mdx-blog my-blog / npm create mdx-blog my-blog if you prefer).
The CLI will prompt you for your project name and package manager (pnpm, npm, or yarn), install the dependencies, and set up your git repository.
Once it finishes, jump into the directory and fire up the development server:
cd my-blog
pnpm devVisit http://localhost:3000—your blog is live locally.
2. Make it yours with a single file
Instead of hunting through layout files, Tailwind configs, and metadata tags, open:
src/blog.config.tsThis single file drives the entire site. You can update your details in 30 seconds:
export const blogConfig = {
site: {
title: "Jane Doe",
description: "Software Engineer & Systems Enthusiast",
url: "https://yourdomain.com",
tagline: "Notes on software architecture, tooling, and shipping clean code.",
},
author: {
name: "Jane Doe",
role: "Senior Staff Engineer",
avatar: "/avatar.jpg",
bio: "Building distributed systems and sharing lessons along the way.",
social: {
github: "https://github.com/janedoe",
linkedin: "https://linkedin.com/in/janedoe",
x: "https://x.com/janedoe",
instagram: "https://instagram.com/janedoe",
},
},
colors: {
background: "#0f172a", // Change your theme with hex colors
accent: "#38bdf8", // Links, buttons, and highlights
hover: "#7dd3fc",
surface: "#1e293b",
text: "#f8fafc",
textMuted: "#94a3b8",
border: "#334155",
},
};Drop your photo into public/avatar.jpg, adjust the palette, and your entire site re-themes instantly.
3. Write your first post
Adding a new post is as simple as creating a folder under src/app/(posts)/:
src/app/(posts)/my-first-post/page.mdExport your metadata at the top, then start writing in standard Markdown:
export const metadata = {
title: "My First Post",
date: "2026-11-21",
description: "A quick note on getting started.",
};
Here is my opening thought. Writing in plain Markdown feels good.
## Code blocks that just work
Syntax highlighting is powered by Shiki with automatic line formatting and a built-in copy button:
```typescript
function greet(name: string): string {
return `Hello, ${name}!`;
}
\```You can even include interactive Mermaid flowcharts and diagrams directly inside your articles—they render crisp SVGs and include a fullscreen lightbox modal when clicked.
4. Update your resume
One of my favorite features is the built-in /resume page (src/app/resume/page.md).
It reads like a clean, distraction-free document on the web, but click the "Print / Save PDF" button (or press Cmd + P), and custom print CSS kicks in:
- Navigation headers and footers disappear.
- Screen dark mode transitions to crisp, high-contrast black-and-white.
- Margins and typography lock to standard US Letter / A4 paper proportions.
No more fighting with Google Docs or maintaining separate Word files whenever you update your experience.
5. Deploy to Vercel in 1 click
When you’re ready to share your blog with the world:
- Push your repository to GitHub:
git add . git commit -m "feat: initial blog setup" git remote add origin https://github.com/your-username/my-blog.git git push -u origin main - Import the repo into Vercel.
- Click Deploy.
Vercel will detect Next.js automatically and build the static output. It includes pre-configured RSS feeds (/rss.xml), sitemaps (/sitemap.xml), dynamic OpenGraph social cards, and privacy-friendly analytics.
That’s all it takes. If you try it out and build your own blog with it, let me know or drop a star on the GitHub repository—I’d love to see what you build!