--- title: "Next.js Markdown Blog: Complete Static Guide for Developers" slug: "nextjs-markdown-blog-complete-static-guide" published: "2026-03-15" updated: "2026-04-06" categories: - "Next.js" tags: - "next.js markdown blog" - "markdown blog" - "static blog Next.js" - "gray-matter" - "remark" - "markdown to HTML" - "git-based blogging" - "nextjs blog tutorial" - "static site generation" - "tailwind prose styling" llm-intent: "reference" audience-level: "intermediate" framework-versions: - "next.js" - "typescript" - "remark" - "remark-html" - "remark-parse" status: "stable" llm-purpose: "Next.js markdown blog: learn to build a static, git-backed blog with gray-matter and remark for SEO-friendly posts. Step-by-step implementation and…" llm-prereqs: - "Access to Next.js" - "Access to TypeScript" - "Access to remark" - "Access to remark-html" - "Access to remark-parse" llm-outputs: - "Completed outcome: Next.js markdown blog: learn to build a static, git-backed blog with gray-matter and remark for SEO-friendly posts. Step-by-step implementation and…" --- **Summary Triples** - (Next.js Markdown Blog: Complete Static Guide for Developers, focuses-on, Next.js markdown blog: learn to build a static, git-backed blog with gray-matter and remark for SEO-friendly posts. Step-by-step implementation and…) - (Next.js Markdown Blog: Complete Static Guide for Developers, category, general) ### {GOAL} Next.js markdown blog: learn to build a static, git-backed blog with gray-matter and remark for SEO-friendly posts. Step-by-step implementation and… ### {PREREQS} - Access to Next.js - Access to TypeScript - Access to remark - Access to remark-html - Access to remark-parse ### {STEPS} 1. Install markdown dependencies 2. Define TypeScript types 3. Convert markdown to HTML 4. Read and parse files 5. Filter and sort posts by date 6. Create reusable components 7. Generate static pages 8. Configure images and deploy 9. Extend and migrate later # Next.js Markdown Blog: Complete Static Guide for Developers > Next.js markdown blog: learn to build a static, git-backed blog with gray-matter and remark for SEO-friendly posts. Step-by-step implementation and… Matija Žiberna · 2026-03-15 I was building the Farmica platform when I realized we needed a blog system that didn't require a database or monthly CMS costs. After researching headless CMS options, API complexity, and vendor lock-in, I decided to build something simpler: a markdown-based blog where content lives in git, styling is handled by components, and everything deploys as static HTML. This guide walks you through the exact implementation I developed, which is now powering the Farmica blog. ## Why This Approach? Before diving into the code, let me explain why this solution is valuable. You get the simplicity of markdown files (anyone can write `git commit` a post), the control of a custom implementation (no vendor lock-in), and the performance of static generation (fast everywhere, minimal server load). If you later decide to migrate to a headless CMS, the architecture supports it—just replace the file reading with API calls. The blog you'll build here supports YAML frontmatter for metadata, automatic date-based publishing, SEO optimization, responsive design, and beautiful prose styling. No admin panel needed. ## Architecture Overview The system works in three layers: **Content Layer**: Markdown files in `content/blog/` with YAML frontmatter containing title, description, image, date, author, and slug. **Processing Layer**: TypeScript utilities that read markdown files, parse frontmatter, convert markdown to HTML, and filter posts by publish date. **Presentation Layer**: React components that accept data as props (no hardcoded content), making it easy to switch from files to an API later. Each part is decoupled, so you can modify one without touching the others. ## Step 1: Install Dependencies Start by adding the markdown parsing libraries to your Next.js project: ```bash npm install remark remark-html remark-parse rehype-stringify gray-matter ``` Or with pnpm: ```bash pnpm add remark remark-html remark-parse rehype-stringify gray-matter ``` These packages handle the heavy lifting: `gray-matter` extracts YAML frontmatter from your markdown files, and `remark` converts the markdown content to HTML. This separation lets us handle metadata and content independently. ## Step 2: Define Types Create a TypeScript file to define the structure of your blog posts. This ensures type safety throughout your application and makes the data flow clear. ```typescript // types/blog.ts export interface BlogPostFrontmatter { title: string; description: string; image: string; date: string; author: string; authorImage?: string; slug: string; } export interface BlogPost extends BlogPostFrontmatter { content: string; htmlContent: string; } export interface BlogPostCardProps { title: string; description: string; slug: string; date: string; author: string; image: string; } ``` The `BlogPostFrontmatter` interface matches the YAML structure in your markdown files. The `BlogPost` extends it with `content` (raw markdown) and `htmlContent` (converted HTML). The `BlogPostCardProps` defines what the card component needs for the blog listing. ## Step 3: Create Markdown Processing Utilities Now create a utility file that converts markdown to HTML. This is straightforward with remark—we pipe the markdown through parsers and formatters. ```typescript // lib/markdown.ts import { remark } from "remark"; import remarkHtml from "remark-html"; import remarkParse from "remark-parse"; export async function markdownToHtml(markdown: string): Promise { const result = await remark() .use(remarkParse) .use(remarkHtml) .process(markdown); return result.toString(); } ``` This function takes raw markdown and returns HTML. The `remark()` chain applies two plugins: `remarkParse` reads the markdown, and `remarkHtml` converts it to HTML. The `.toString()` at the end gives us a string we can safely render. ## Step 4: Create Post Utilities This is the core of the system—utilities that read your markdown files from disk, parse them, and return structured blog post objects. ```typescript // app/blog/_lib/posts.ts import { readFileSync, readdirSync } from "fs"; import { join } from "path"; import matter from "gray-matter"; import { markdownToHtml } from "@/lib/markdown"; import { BlogPost, BlogPostFrontmatter } from "@/types/blog"; const blogDir = join(process.cwd(), "content", "blog"); export async function getBlogPost(slug: string): Promise { try { const filePath = join(blogDir, `${slug}.md`); const fileContent = readFileSync(filePath, "utf-8"); const { data, content } = matter(fileContent); const htmlContent = await markdownToHtml(content); return { ...(data as BlogPostFrontmatter), content, htmlContent, }; } catch (error) { console.error(`Error reading blog post: ${slug}`, error); return null; } } export async function getAllBlogPosts(): Promise { try { const files = readdirSync(blogDir).filter((file) => file.endsWith(".md")); const posts = await Promise.all( files.map(async (file) => { const slug = file.replace(".md", ""); return getBlogPost(slug); }) ); const today = new Date(); today.setHours(0, 0, 0, 0); return posts .filter((post): post is BlogPost => post !== null) .filter((post) => new Date(post.date) <= today) .sort( (a, b) => new Date(b.date).getTime() - new Date(a.date).getTime() ); } catch (error) { console.error("Error reading blog posts", error); return []; } } export function getBlogPostSlugs(): string[] { try { const files = readdirSync(blogDir).filter((file) => file.endsWith(".md")); return files.map((file) => file.replace(".md", "")); } catch (error) { console.error("Error reading blog post slugs", error); return []; } } ``` Here's what each function does: `getBlogPost(slug)` reads a single markdown file, uses `gray-matter` to split the frontmatter from content, converts the markdown to HTML, and returns everything together. If the file doesn't exist, it returns null gracefully. `getAllBlogPosts()` reads all markdown files in the blog directory, fetches each one, filters out any that failed to load, excludes posts with future dates (so you can schedule posts), and sorts by date newest first. `getBlogPostSlugs()` returns just the list of slugs, which Next.js uses for static generation. Notice the date filtering: `new Date(post.date) <= today` means posts only appear once their publish date arrives. This lets you write posts ahead of time without them showing up publicly. ## Step 5: Create Blog Components Now we build the React components that display the blog. These components accept data as props—no hardcoded content, making it easy to swap the file-based system for an API later. First, the metadata component that displays date and author with icons: ```typescript // components/blog/blog-meta.tsx import { CalendarBlank, User } from "@phosphor-icons/react/dist/ssr"; export interface BlogMetaProps { date: string; author: string; } export function BlogMeta({ date, author }: BlogMetaProps) { const formattedDate = new Date(date).toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric", }); return (
{formattedDate}
{author}
); } ``` This component formats the date into a readable string and displays both date and author with icons. The styling uses Tailwind's responsive classes to stack on mobile. The blog header component displays at the top of the post: ```typescript // components/blog/blog-header.tsx import Image from "next/image"; import { BlogMeta } from "./blog-meta"; export interface BlogHeaderProps { title: string; description: string; image: string; date: string; author: string; } export function BlogHeader({ title, description, image, date, author, }: BlogHeaderProps) { return (

{title}

{description}

{title}
); } ``` This stacks the title, description, metadata, and featured image. The `Image` component from Next.js handles optimization automatically. The content component renders the HTML markdown. This is where styling matters—we use Tailwind's arbitrary selector syntax to style HTML elements generated from markdown: ```typescript // components/blog/blog-content.tsx "use client"; export interface BlogContentProps { htmlContent: string; } export function BlogContent({ htmlContent }: BlogContentProps) { return (
); } ``` The `[&_selector]` syntax targets elements within the div. `[&_h2]` means "h2 tags inside this div get these styles." This approach gives you complete control over markdown styling without relying on a prose plugin. The author component displays author info at the end of the post: ```typescript // components/blog/blog-author.tsx import Image from "next/image"; export interface BlogAuthorProps { name: string; image?: string; bio?: string; } export function BlogAuthor({ name, image, bio }: BlogAuthorProps) { return (
{image && (
{name}
)}

{name}

{bio && (

{bio}

)}
); } ``` Finally, the card component for the blog listing: ```typescript // components/blog/blog-post-card.tsx import Link from "next/link"; import Image from "next/image"; import { BlogMeta } from "./blog-meta"; export interface BlogPostCardProps { title: string; description: string; slug: string; date: string; author: string; image: string; } export function BlogPostCard({ title, description, slug, date, author, image, }: BlogPostCardProps) { return (
{title}

{title}

{description}

); } ``` The card wraps in a link, contains the image with a hover scale effect, and displays the title, description, and metadata. The `mt-auto` pushes the metadata to the bottom regardless of content height. ## Step 6: Create Pages Now create the pages that display your blog. First, the listing page that shows all posts: ```typescript // app/blog/page.tsx import { Metadata } from "next"; import { Section } from "@/components/layout/section"; import { BlogPostCard } from "@/components/blog/blog-post-card"; import { getAllBlogPosts } from "./_lib/posts"; export const metadata: Metadata = { title: "Blog | Your Site", description: "Insights and tips on [your topic]. Read articles from our team.", openGraph: { title: "Blog | Your Site", description: "Insights and tips on [your topic]. Read articles from our team.", type: "website", }, }; export default async function BlogPage() { const posts = await getAllBlogPosts(); return (

Blog

Articles and insights from our team

{posts.length > 0 ? (
{posts.map((post) => ( ))}
) : (

No blog posts published yet. Check back soon!

)}
); } ``` This page fetches all posts, displays them in a responsive grid, and handles the empty state gracefully. The metadata export ensures good SEO on the listing page. Now the dynamic post page: ```typescript // app/blog/[slug]/page.tsx import { Metadata } from "next"; import { notFound } from "next/navigation"; import { Section } from "@/components/layout/section"; import { BlogHeader } from "@/components/blog/blog-header"; import { BlogContent } from "@/components/blog/blog-content"; import { BlogAuthor } from "@/components/blog/blog-author"; import { getBlogPost, getBlogPostSlugs } from "../_lib/posts"; interface BlogPostPageProps { params: Promise<{ slug: string; }>; } export async function generateMetadata({ params, }: BlogPostPageProps): Promise { const { slug } = await params; const post = await getBlogPost(slug); if (!post) { return { title: "Post not found", }; } return { title: `${post.title} | Your Site Blog`, description: post.description, openGraph: { title: post.title, description: post.description, type: "article", publishedTime: post.date, authors: [post.author], images: [ { url: post.image, width: 1200, height: 630, alt: post.title, }, ], }, twitter: { card: "summary_large_image", title: post.title, description: post.description, images: [post.image], }, }; } export async function generateStaticParams() { const slugs = getBlogPostSlugs(); return slugs.map((slug) => ({ slug, })); } export default async function BlogPostPage({ params }: BlogPostPageProps) { const { slug } = await params; const post = await getBlogPost(slug); if (!post) { notFound(); } return ( <>
); } ``` The key points here: `generateMetadata()` creates proper Open Graph tags for social sharing and SEO. Notice the structure matches what social platforms expect. `generateStaticParams()` tells Next.js which routes to pre-render. It calls `getBlogPostSlugs()` and creates a route for each one. This is what enables static generation—Next.js runs this at build time and creates HTML files for every post. The page component itself is straightforward: fetch the post, or show a 404 if it doesn't exist, then render the sections. ## Step 7: Create Your First Post Create the content directory and add a markdown file: ```bash mkdir -p content/blog ``` Then create your first post: ```markdown // content/blog/your-first-post.md --- title: "Your First Post Title" description: "A brief description that appears in listings and metadata" image: "https://example.com/image.jpg" date: "2024-02-26" author: "Your Name" authorImage: "https://example.com/author.jpg" slug: "your-first-post" --- # Your First Post This is the start of your markdown content. Write normally in markdown—headings, lists, bold, italics, code blocks, everything works. ## Markdown Features Supported You can use all standard markdown features: - **Bold text** with `**bold**` - *Italic text* with `*italic*` - [Links](https://example.com) with `[text](url)` - Code blocks with triple backticks - Blockquotes with `>` ## Blockquotes > This is a blockquote. It will be styled with a left border and light background, making it stand out from regular text. ## Code Example ```typescript // Your code examples appear with syntax highlighting const greeting = "Hello, world!"; console.log(greeting); ``` Keep writing. Your content will appear on `/blog` once the build runs. ``` The key point: the frontmatter must match your `BlogPostFrontmatter` interface. The `date` controls when the post becomes visible (posts with future dates won't appear until that date arrives). ## Step 8: Configure Next.js Add external image domains to your Next.js config so images from external URLs work: ```typescript // next.config.ts import type { NextConfig } from "next"; const nextConfig: NextConfig = { images: { remotePatterns: [ { protocol: "https", hostname: "images.unsplash.com", }, { protocol: "https", hostname: "example.com", }, ], }, }; export default nextConfig; ``` Add patterns for any external image hosts you use. This lets Next.js optimize images from those domains. ## Step 9: Build and Deploy When you run the build, Next.js uses `generateStaticParams()` to pre-render every post as static HTML: ```bash npm run build ``` You'll see output like: ``` ✓ Generating static pages using 9 workers (12/12) Route (app) ├ ○ /blog ├ ● /blog/[slug] │ └ /blog/your-first-post ``` The `●` indicates a static page that was pre-rendered. Every post gets its own HTML file. This means your blog loads instantly, requires no server processing, and scales to any traffic level. Deploy the built files to any static host: Vercel, Netlify, CloudFlare Pages, or traditional CDN. Because everything is pre-rendered, you don't need a Node.js server. ## Extending the System ### Adding More Posts Just create new markdown files in `content/blog/`. On the next build, they'll automatically appear. No database migrations, no admin panel needed. ### Adding Categories or Tags Extend your `BlogPostFrontmatter` interface to include `tags: string[]`. Then in `getAllBlogPosts()`, filter by tag before returning. The component-based design means you only change the data layer—presentation stays the same. ### Adding Search Collect all posts and their content at build time, generate a JSON index, and search client-side. Keeps everything static while providing search capability. ### Adding Comments Most static blog systems use Disqus, Giscus, or Utterances for comments. These are embedded via script tags, requiring zero server infrastructure. ### Migrating to a CMS When you're ready for a database, replace `getBlogPost()` and `getAllBlogPosts()` with API calls. Your components don't change—they just receive data from an API instead of files. This is the power of the architecture. ## The Value of This Approach You've now built a blog system that's fast, simple, and future-proof. No monthly fees, no vendor lock-in, no databases to maintain. Content lives in git alongside your code. Writers can use any markdown editor. The build process handles everything else. As your platform grows and you need features like drafts, scheduled posts, or team collaboration, you can add them by modifying the file-based system or switching to a headless CMS—your components don't care where the data comes from. This is what powers production blogs at companies like Vercel, Stripe, and Segment. It's proven architecture that scales from first post to thousands. --- Let me know in the comments if you have questions about the implementation, and subscribe for more practical development guides. Thanks, Matija ## LLM Response Snippet ```json { "goal": "Next.js markdown blog: learn to build a static, git-backed blog with gray-matter and remark for SEO-friendly posts. Step-by-step implementation and…", "responses": [ { "question": "What does the article \"Next.js Markdown Blog: Complete Static Guide for Developers\" cover?", "answer": "Next.js markdown blog: learn to build a static, git-backed blog with gray-matter and remark for SEO-friendly posts. Step-by-step implementation and…" } ] } ```