This guide walks you through creating a static blog in Next.js 15 using Markdown files, the App Router, and the latest Next.js features.
Prerequisites
- Basic knowledge of React and Next.js
- Node.js and npm installed
Steps
1. Set up a New Next.js Project
Start by creating a new Next.js project:
npx create-next-app@latest my-blog
cd my-blog
2. Install Dependencies
To parse Markdown, we’ll use gray-matter for front matter and remark with remark-html to convert Markdown to HTML.
npm install gray-matter remark remark-html
3. Project Structure
Set up the following folder structure:
my-blog/
├── app/
│ ├── blog/
│ │ ├── [slug]/
│ │ │ └── page.tsx
│ └── page.tsx
├── posts/
├── lib/
│ └── markdown.ts
└── public/
└── images/
4. Write Blog Posts in Markdown
Create your Markdown files under the posts folder with the .md extension. Add front matter (metadata) to each Markdown file for the title, date, and description. Here’s an example file named hello-world.md:
---
title: "Hello World"
date: "2023-10-31"
description: "This is my first blog post in Next.js!"
---
## Welcome to my blog
This is the first post on my blog made with Next.js and Markdown.
5. Create a Markdown Parsing Function
In the lib/markdown.ts file, create a function to read and parse the Markdown files:
import fs from 'fs';
import path from 'path';
import matter from 'gray-matter';
import { remark } from 'remark';
import html from 'remark-html';
const postsDirectory = path.join(process.cwd(), 'posts');
export function getPostSlugs() {
return fs.readdirSync(postsDirectory);
}
export function getPostBySlug(slug: string) {
const fullPath = path.join(postsDirectory, `${slug}.md`);
const fileContents = fs.readFileSync(fullPath, 'utf8');
const { data, content } = matter(fileContents);
return { data, content };
}
export async function getPostData(slug: string) {
const { data, content } = getPostBySlug(slug);
const processedContent = await remark().use(html).process(content);
const contentHtml = processedContent.toString();
return { slug, metadata: data, contentHtml };
}
export function getAllPosts() {
const slugs = getPostSlugs();
const posts = slugs.map(slug => {
const { data } = getPostBySlug(slug.replace(/\.md$/, ''));
return { slug: slug.replace(/\.md$/, ''), metadata: data };
});
return posts.sort((post1, post2) => (post1.metadata.date < post2.metadata.date ? 1 : -1));
}
6. Display All Blog Posts
In app/blog/page.tsx, create the page that lists all blog posts. This page will retrieve the metadata for each post and display it.
import Link from 'next/link';
import { getAllPosts } from '@/lib/markdown';
export default function BlogPage() {
const posts = getAllPosts();
return (
<div>
<h1>Blog</h1>
<ul>
{posts.map(({ slug, metadata }) => (
<li key={slug}>
<Link href={`/blog/${slug}`}>
<h2>{metadata.title}</h2>
<p>{metadata.description}</p>
<small>{metadata.date}</small>
</Link>
</li>
))}
</ul>
</div>
);
}
7. Generate Individual Blog Pages
In app/blog/[slug]/page.tsx, set up the page to display a single blog post based on its slug.
import { getPostData, getPostSlugs } from '@/lib/markdown';
import { notFound } from 'next/navigation';
interface PostPageProps {
params: { slug: string };
}
export async function generateStaticParams() {
const slugs = getPostSlugs();
return slugs.map(slug => ({ slug: slug.replace(/\.md$/, '') }));
}
export async function generateMetadata({ params }: PostPageProps) {
const post = await getPostData(params.slug);
if (!post) return { title: "Post not found" };
return { title: post.metadata.title };
}
export default async function PostPage({ params }: PostPageProps) {
const post = await getPostData(params.slug);
if (!post) return notFound();
return (
<article>
<h1>{post.metadata.title}</h1>
<p>{post.metadata.date}</p>
<div dangerouslySetInnerHTML={{ __html: post.contentHtml }} />
</article>
);
}
8. Create the Homepage
In app/page.tsx, set up a simple homepage that links to the blog section.
import Link from 'next/link';
export default function Home() {
return (
<main>
<h1>Welcome to My Blog</h1>
<p>This is a blog created with Next.js and Markdown.</p>
<Link href="/blog">Go to Blog</Link>
</main>
);
}
9. Add CSS Styling (Optional)
If you want to add some basic styling, you can do so in a globals.css file inside the app directory. Then, import this file in app/layout.tsx.
10. Run Your Blog
Start the development server:
npm run dev
Visit http://localhost:3000/blog to see the list of posts and click on any post to see its full content.
