How to Build a Free Static Blog with Next.js and GitHub Pages

A static blog is a website made of pre-built HTML, CSS, and JavaScript files with no server or database behind it. Everything is generated at build time, so it loads fast, costs nothing to host, and is hard to break. This guide shows how I built this blog with Next.js and deployed it free on GitHub Pages.

01The stack: Next.js, Markdown, and GitHub Pages

I wanted a fast, good-looking blog that costs nothing to host and is trivial to update. A static site on free hosting is the obvious answer. Here is the stack:

• Next.js (App Router) exported to static HTML with output: 'export'.
• CSS Modules with an OKLCH design-token system for theming.
• Markdown files compiled at build time with remark.
• GitHub Pages for hosting, with GitHub Actions for automatic deploys.

02Why use Next.js static export for a blog

GitHub Pages only serves static files, with no servers or databases. Next.js handles this with a single config flag:

// next.config.mjs
const nextConfig = {
  output: 'export',
  basePath: '/blogs',
  images: { unoptimized: true },
};

Because the site lives at a sub-path (/blogs), I set a basePath so every asset and link URL resolves correctly.

03How to write posts in Markdown

Each post is a Markdown file with a small frontmatter block:

---
title: My Post
date: 2026-06-20
excerpt: A short summary.
tags: [example]
author: Brian Castelino
authorUrl: https://www.linkedin.com/in/cas7elino/
---

Your content here.

author and authorUrl are optional. If you omit them, every post defaults to my name linked to my LinkedIn, so the byline stays consistent across the site.

The build reads every file in content/posts, generates a static page for each, and lists them on the home page sorted by date.

04How to deploy a Next.js blog to GitHub Pages

Deployment runs automatically through GitHub Actions on every push to main:

1. Push your new post to the main branch.
2. A GitHub Actions workflow runs next build, which exports the site to the out/ folder.
3. The workflow publishes out/ to GitHub Pages.
4. Wait about a minute, and the post is live.

That is the whole system: simple, fast, and free.

05Related reading

New here? Start with why I built The Brian Journal, or read my first deep dive on Databricks Data + AI Summit 2026.