Blog template

A minimal blog template built with Next.js App Router, TypeScript, Tailwind CSS, and MDX.

Features

• Markdown/MDX posts with YAML frontmatter
• React components inside posts (charts, widgets, etc.)
• Paginated home page
• Light / dark theme (next-themes)
• Static generation for posts and listing pages
• loading / error UI, sitemap, and robots

Project structure

src/
  app/                 # App Router routes, layouts, loading/error
  components/          # UI + MDX embeds
  content/posts/       # MDX posts
  lib/                 # Post helpers, pagination
  mdx-components.tsx   # Global MDX component map
public/                # Static assets

Blog posts

Add posts as .mdx files in src/content/posts/.

Each file needs this frontmatter:

Key	Value
authors	string[]
date	string in ISO 8601
excerpt	string short summary for cards / SEO
thumbnail	string path or URI under public/
tags	string[]
title	string

Posts are ordered by date descending on the home page.

Interactive components

Global MDX components are registered in src/mdx-components.tsx (for example Counter and SimpleChart).

Use them directly in a post:

<Counter initial={1} />

<SimpleChart caption="Weekly reads" points={[4, 8, 6, 12]} />

Or import a local component in the MDX file:

import { MyScene } from '@/components/mdx/my-scene'

<MyScene />

For heavy client-only libraries (Three.js, etc.), mark the component with 'use client' and load it with next/dynamic if you need to avoid SSR.

Development

Requires Node.js 24 LTS (see .nvmrc).

npm install
npm run dev

Open http://localhost:3000.

npm run build
npm start

Pagination

The home page shows a fixed page size (POSTS_PER_PAGE in src/lib/posts.ts). Later pages live at /page/2, /page/3, and so on.

Deployment

Set NEXT_PUBLIC_SITE_URL to your production origin (used for metadataBase, sitemap, and robots).

Host on any Next.js platform. Vercel is the simplest path for this template.

Inspiration

• Next.js blog starter
• Next.js MDX guide
• Next.js project structure