Setting up a blog can be overwhelming with so many options. After researching the latest tools, I chose Velite for content management and Next.js App Router for the framework. Here's how I built a type-safe, performant blog system that's both developer-friendly and fast.

Why This Stack?

Velite

Type-safe content collections with Zod schemas
Pre-processes markdown at build time (fast!)
Framework agnostic but works seamlessly with Next.js
Simple configuration - just markdown files and a config

Next.js App Router

Built-in support for static generation
Server components by default
Great developer experience

The Setup

1. Install Dependencies

npm install velite zod rehype-pretty-code remark-gfm remark-smartypants shiki

Key packages:

velite - Content management system
rehype-pretty-code - Syntax highlighting (uses Shiki under the hood)
remark-gfm - GitHub Flavored Markdown support
remark-smartypants - Better typography (smart quotes, em dashes)

2. Configure Velite

Create velite.config.ts:

import { defineCollection, defineConfig, s } from "velite";
import remarkGfm from "remark-gfm";
import remarkSmartypants from "remark-smartypants";
import rehypePrettyCode from "rehype-pretty-code";

const blog = defineCollection({
	name: "blog",
	pattern: "blog/**/*.{md,mdx}",
	schema: s.object({
		title: s.string().min(1).max(120),
		date: s.isodate(),
		description: s.string().optional(),
		tags: s.array(s.string()).default([]),
		draft: s.boolean().default(false),
		cover: s.string().optional(),
		slug: s.slug("blog"),
		content: s.markdown(),
	}),
});

export default defineConfig({
	collections: { blog },
	mdx: {
		remarkPlugins: [remarkGfm, remarkSmartypants],
		rehypePlugins: [[rehypePrettyCode, {
			theme: {
				light: "github-light",
				dark: "github-dark",
			},
			keepBackground: false,
		}]],
	},
});

Key decisions:

s.markdown() outputs HTML (simpler than MDX for MVP)
s.slug("blog") validates unique slugs per collection
rehype-pretty-code handles syntax highlighting automatically

3. Content Structure

Organize posts in content/blog/:

content/
  blog/
    hello-world.md
    another-post.md

Each post needs frontmatter:

---
title: "My First Post"
slug: my-first-post
date: "2025-11-04"
description: "A sample blog post"
tags: ["nextjs", "tutorial"]
draft: false
---

# Content here...

4. Build Scripts

Update package.json:

{
  "scripts": {
    "dev": "velite -- -w && next dev",
    "build": "velite && next build",
    "velite": "velite"
  }
}

The -w flag watches for content changes during development.

5. Content Helpers

Create lib/content.ts:

import { blog } from "@/.velite";

export type BlogPost = (typeof blog)[number];

export function getAllPosts(): BlogPost[] {
	return blog
		.filter((p) => !p.draft)
		.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
}

export function getPostBySlug(slug: string): BlogPost | undefined {
	return blog.find((p) => p.slug === slug);
}

Velite generates .velite/index.js which exports typed collections. Import them directly!

6. Blog Pages

Index page (app/blogs/page.tsx):

import { getAllPosts } from "@/lib/content";

export default function BlogPage() {
	const posts = getAllPosts();
	
	return (
		<div>
			{posts.map((post) => (
				<Link href={`/blogs/${post.slug}`}>
					{post.title}
				</Link>
			))}
		</div>
	);
}

Post page (app/blogs/[slug]/page.tsx):

import { getPostBySlug, getAllPosts } from "@/lib/content";

export function generateStaticParams() {
	return getAllPosts().map((p) => ({ slug: p.slug }));
}

export default async function BlogPostPage({ params }: { params: Promise<{ slug: string }> }) {
	const { slug } = await params;
	const post = getPostBySlug(slug);
	
	return (
		<article>
			<h1>{post.title}</h1>
			<div dangerouslySetInnerHTML={{ __html: post.content }} />
		</article>
	);
}

Enhanced Features

Syntax Highlighting

rehype-pretty-code automatically:

Detects code block languages
Applies Shiki syntax highlighting
Generates themed HTML (supports light/dark modes)

Copy Buttons & Language Labels

I added a client component that enhances code blocks:

// components/code-block.tsx
"use client";

export function CodeBlockEnhancer({ containerRef }) {
	useEffect(() => {
		// Find all code blocks
		// Extract language from className
		// Add header with language label + copy button
	}, []);
}

This dynamically adds:

Language label (e.g., "TYPESCRIPT")
Copy button with visual feedback
Proper styling that matches your design system

Markdown Styling

Custom CSS for readable content:

.markdown-content h1 {
	@apply text-2xl sm:text-3xl md:text-4xl font-display;
}

.markdown-content pre {
	@apply bg-muted border rounded-lg p-4;
}

/* Syntax highlighting styles */
.markdown-content [data-rehype-pretty-code-figure] {
	/* Styles for highlighted code */
}

Key Learnings

Type safety matters - Velite's Zod schemas catch errors at build time
Build-time processing - Converting markdown to HTML at build keeps runtime fast
Framework agnostic - Velite works with any framework, but Next.js integration is seamless
Simple MVP first - Started with s.markdown() (HTML), can upgrade to s.mdx() later if needed

What's Next?

Potential enhancements:

RSS feed generation
Sitemap with next-sitemap
Tag-based filtering
Reading time estimates
Search functionality with Pagefind
OG image generation per post

Resources

The best part? Everything is type-safe, fast, and maintainable. Adding a new blog post is as simple as creating a markdown file!