Building a Static Blog with Next.js

You don't need a CMS or a database to run a blog. This starter kit includes a static blog powered by Markdown files — a few utility functions and a directory of .md files is the whole system.

How It Works

Every blog post is a .md file inside the content/blog/ directory. Each file uses YAML frontmatter at the top for metadata — title, description, keywords, and publish date — followed by the article body in standard Markdown.

---
title: "Your Post Title"
description: "A short summary for SEO and previews."
keywords: ["topic-a", "topic-b"]
publishedAt: "2026-01-15"
---

Your article content goes here.

At build time, Next.js reads these files, parses the frontmatter with gray-matter, and generates a static HTML page for each post. No API calls, no database queries, no loading spinners.

The build pipeline has three steps. First, gray-matter reads each .md file and splits it into two parts: the YAML frontmatter (structured metadata) and the raw Markdown body. Second, the Markdown body is converted to HTML — headings become <h2> tags, code blocks get syntax highlighting, and links become proper <a> elements. Third, Next.js wraps that HTML in your React layout, injects the metadata, and outputs a fully self-contained .html file for each post.

The result is a set of plain HTML files sitting in the .next output directory. When you deploy, your hosting provider uploads these files to edge servers around the world. A visitor in Tokyo gets the same instant response as a visitor in New York — there's no origin server to round-trip to.

Why Static Generation?

Static pages are served directly from a CDN. That means:

• Fast — no server round-trips, no cold starts, no query latency
• Reliable — no database to go down, no API rate limits to hit
• Cheap — static files cost almost nothing to host
• SEO-friendly — search engines get fully rendered HTML immediately

For content that changes infrequently (like blog posts), static generation makes more sense than server-side rendering. The tradeoff is that new posts require a rebuild and deploy, but for a blog that publishes once a week, that is not a real constraint.

The performance difference is measurable. Static pages served from a CDN typically respond in 20–50 milliseconds — that's the time to first byte (TTFB). Server-rendered pages, by comparison, range from 100ms on a warm serverless function to 300–900ms when the server is cold or under load. That gap matters because Google uses TTFB as a ranking signal, and users perceive anything over 200ms as noticeably slower.

Hosting costs reflect this too. A static blog on Vercel's free tier or Cloudflare Pages handles thousands of daily visitors without hitting any limits. A server-rendered equivalent needs compute resources that scale with traffic — every request spins up a function, queries data, renders HTML, and sends it back. For a personal blog or small company site, that's overhead you don't need.

SEO Built In

Each blog post automatically generates:

• Open Graph metadata for rich previews on social media
• JSON-LD structured data so search engines understand the article schema
• Canonical URLs to prevent duplicate content issues
• Semantic HTML with proper heading hierarchy

You don't have to configure any of this. Write a Markdown file, add frontmatter, and Next.js generates the metadata at build time.

Here's what each one does in practice:

• JSON-LD tells search engines what type of content the page contains — article, author, publish date, description. Google uses this to generate rich results: those enhanced search listings with dates, author names, and article snippets that get higher click-through rates than plain blue links.
• Open Graph tags control how your post looks when someone shares it on social media or messaging apps. Without them, platforms pull whatever text and image they can find — usually the wrong ones. With OG tags, you control the title, description, and preview image exactly.
• Canonical URLs prevent duplicate content penalties. If your post is accessible at both /blog/my-post and /blog/my-post?ref=twitter, the canonical tag tells Google which URL is the "real" one.

You can validate your structured data using Google's Rich Results Test — paste your post URL after deploying and it shows exactly what Google sees.

Adding a New Post

1. Create a new .md file in content/blog/
2. Add frontmatter with title, description, keywords, and publishedAt
3. Write your content in Markdown
4. The post appears on /blog automatically, sorted by date

No migrations, no admin panels, no deploy scripts. Just files in a folder.

A few things to keep in mind when creating posts:

• Slug = filename — The filename becomes the URL. my-first-post.md becomes /blog/my-first-post. Use lowercase, hyphen-separated names — no spaces, no special characters.
• Description length matters for SEO — Keep it between 100 and 160 characters. Search engines truncate anything longer, and anything shorter wastes space in search results.
• Keywords are arrays — Use 3-5 specific terms like ["next.js blog", "static generation"], not generic words like ["blog", "code"]. These feed into meta tags and help search engines categorize your content.
• Dates control ordering — Posts sort by publishedAt descending. Future dates won't break anything, but the post will appear at the top of the list before it's actually "published" in any meaningful sense.

When Static Isn't Enough

Static generation has real limits. Every content change requires a full rebuild and deploy — for a 10-post blog, that takes seconds; for a site with thousands of pages, it can mean minutes of build time before anything goes live.

You also lose anything dynamic. Comments, user accounts, real-time data — none of that works with plain static files. You can bolt on external services (Disqus for comments, Supabase for auth), but at that point you're assembling infrastructure that a server-rendered app handles natively.

The middle ground is Incremental Static Regeneration (ISR). Instead of rebuilding the entire site, ISR regenerates individual pages in the background after a set interval. A visitor hits the page, gets the cached version instantly, and Next.js rebuilds that single page behind the scenes. You get CDN-level speed with near-real-time content updates — the tradeoff is a brief window where a visitor might see stale content.

For a blog that publishes a few posts per month, full static generation is the simpler choice. ISR starts to matter when you have hundreds of pages or content that changes multiple times a day.

Further Reading

• Next.js Static Generation — How Next.js pre-renders pages at build time
• gray-matter on npm — YAML frontmatter parser used for blog metadata
• MDX Documentation — An alternative approach using JSX in Markdown