Next.js Blog Starter

An awesome blog system based on Next.js.

Default	Nature

✨ Features

Content & UX

Rich MDX Support - GFM, KaTeX math, admonitions, emoji shortcodes, Shiki-based syntax highlighting, live code editor with Sandpack
Modern UI/UX - Dark mode, smooth animations, command menu (⌘K), responsive design, progress indicators
Advanced Navigation - Auto-generated TOC with active tracking, previous/next posts, tag filtering, search
Social & Interactive - Giscus comments, share buttons, GitHub integration
Bilingual (i18n) - Full English/Chinese support with locale-specific routing

LLM-Ready

AI Agent Actions - One-click "Read with Claude" or "Read with ChatGPT" to open articles in AI assistants with context
llms.txt API - Auto-generated structured feed for LLM consumption at /llms.txt

Developer Experience

Modern Stack - Next.js App Router + Turbopack, React Compiler, TypeScript strict mode
Comprehensive Testing - Vitest (unit), Playwright (E2E), Testing Library
Code Quality - ESLint, Stylelint, Prettier, CI/CD with GitHub Actions
Performance - Automatic code splitting, image optimization, Rust-based builds
SEO Ready - Meta tags, sitemap, robots.txt, Open Graph, Twitter Cards

📑 Post Template

.yaml front matter + .mdx body:

---
layout: post
title: 'Your Post Title'
description: 'Your post description'
author: 'Your Name'
date: 2026-01-01
thumbnail: '/thumbnails/your-thumbnail.jpg'
tags:
  - Your Tag 1
  - Your Tag 2
  - Your Tag 3
---

# Your Post Title

## Introduction

Your content here...

## Math Support

Inline math: $E = mc^2$

Block math:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

## Admonitions

:::note
This is a note admonition.
:::

:::tip
This is a tip admonition.
:::

:::warning
This is a warning admonition.
:::

🚀 Quick Start

Prerequisites

Node.js 18.17 or later
pnpm 10 or later

Installation

git clone https://github.com/sabertazimi/blog
cd blog
pnpm install

Development

pnpm dev

Open the source code and start editing!

Your site is now running at http://localhost:3000!

Build

# Build for production
pnpm build

# Start production server
pnpm serve

🌠 Deployment

Build for production:

pnpm build

The optimized production build will be in the .next folder.

🔧 Configuration

Site Configuration

Edit src/lib/site.ts to customize your blog:

export const site = {
  author: 'Your Name',
  url: 'https://yourblog.com',
  // ... more settings
}

i18n Configuration

Configure supported locales in src/i18n/routing.ts:

export const routing = defineRouting({
  locales: ['en-US', 'zh-CN'],
  defaultLocale: 'en-US',
  localePrefix: 'always',
})

Add translations in messages/[locale].json:

{
  "site": {
    "title": "Your Blog Title",
    "description": "Your blog description"
  },
  "common": {
    "loading": "Loading...",
    "backToTop": "Back to top"
  }
}

Organize MDX posts by locale in content/[locale]/:

content/
├── en-US/
│   ├── my-first-post.mdx
│   └── ...
└── zh-CN/
    ├── my-first-post.mdx
    └── ...

Theme Customization

The blog uses Tailwind CSS with custom CSS variables. Edit src/app/globals.css to customize colors:

:root {
  --background: oklch(100% 0 0deg);
  --foreground: oklch(14.5% 0 0deg);
  --primary: oklch(20.5% 0 0deg);
  /* ... more colors */
}

.dark {
  --background: oklch(14.5% 0 0deg);
  --foreground: oklch(98.5% 0 0deg);
  /* ... more colors */
}

Nature theme:

pnpm dlx shadcn@latest add https://tweakcn.com/r/themes/nature.json

Claude theme:

pnpm dlx shadcn@latest add https://tweakcn.com/r/themes/claude.json

Shadcn UI Registries

The project includes multiple component registries in components.json:

@animate-ui: https://animate-ui.com - Animated UI components
@magicui: https://magicui.design - Magic UI components
@shadcn-studio: https://shadcnstudio.com - Shadcn Studio components, blocks, and themes

You can add components from these registries:

pnpm dlx shadcn@latest add @magicui/morphing-text
pnpm dlx shadcn@latest add @animate-ui/gravity-stars

MDX Components

Customize MDX components in src/components/post-content.tsx:

const mdxComponents = {
  aside: MDXAdmonition,
  img: MDXImage,
  pre: MDXCode,
  Button,
  Editor: MDXEditor,
  // Add your custom components here
}

📂 Project Structure

.
├── node_modules/
├── src/
│   ├── app/                       # Next.js App Router pages
│   │   ├── [locale]/              # Locale-based routing
│   │   │   ├── about/             # About page
│   │   │   ├── post/[slug]/       # Dynamic post pages
│   │   │   ├── posts/             # All posts page
│   │   │   ├── tag/[tagName]/     # Tag filter pages
│   │   │   ├── layout.tsx         # Locale layout
│   │   │   ├── page.tsx           # Home page
│   │   │   └── not-found.tsx      # 404 page
│   │   ├── globals.css            # Global styles
│   │   ├── providers.tsx          # Context providers
│   │   ├── robots.ts              # robots.txt generation
│   │   └── sitemap.ts             # Sitemap generation
│   ├── components/                # React components
│   │   ├── ui/                    # Shadcn UI components
│   │   │   ├── button.tsx
│   │   │   ├── card.tsx
│   │   │   ├── dialog.tsx
│   │   │   ├── skeleton.tsx
│   │   │   └── ...
│   │   ├── language-switcher.tsx  # Language switcher
│   │   ├── mdx-code.tsx           # Code block with Shiki
│   │   ├── mdx-editor.tsx         # Live code editor with Sandpack
│   │   ├── mdx-image.tsx          # Optimized image component
│   │   ├── post-card.tsx          # Post card component
│   │   ├── post-content.tsx       # MDX content renderer
│   │   └── ...
│   ├── i18n/                      # Internationalization
│   │   ├── routing.ts             # i18n routing config
│   │   ├── request.ts             # Request config
│   │   ├── navigation.ts          # Navigation helpers
│   │   └── utils.ts               # i18n utilities
│   ├── layouts/                   # Layout components
│   │   └── default-layout.tsx
│   ├── lib/                       # Utility functions
│   │   ├── get-posts-data.ts      # MDX processing
│   │   ├── utils.ts               # Helper functions
│   │   ├── get-routes.ts          # Route generation
│   │   ├── seo.ts                 # SEO utilities
│   │   └── ...
│   ├── types/                     # TypeScript type definitions
│   │   ├── index.d.ts
│   │   └── i18n.ts
│   └── proxy.ts                   # next-intl middleware
├── content/                       # Blog posts (.mdx files)
│   ├── en-US/                     # English posts
│   │   ├── post1.mdx
│   │   └── ...
│   └── zh-CN/                     # Chinese posts
│       ├── post1.mdx
│       └── ...
├── messages/                      # i18n translation files
│   ├── en-US.json
│   └── zh-CN.json
├── public/                        # Static assets
│   ├── fonts/
│   ├── images/
│   ├── thumbnails/
│   └── ...
├── e2e/                           # Playwright E2E tests
│   ├── home.spec.ts
│   ├── i18n.spec.ts
│   └── ...
├── .github/                       # GitHub workflows
│   └── workflows/
│       ├── ci.yml
│       └── codeql-analysis.yml
├── .gitignore
├── .prettierrc.json
├── components.json                # Shadcn UI config
├── eslint.config.mjs              # ESLint Flat Config
├── next.config.ts                 # Next.js configuration
├── package.json
├── playwright.config.ts           # Playwright configuration
├── postcss.config.mjs             # PostCSS configuration
├── tsconfig.json                  # TypeScript configuration
├── vitest.config.mts              # Vitest configuration
├── LICENSE
└── README.md

Key Directories

src/app/[locale]/: Locale-based Next.js App Router pages with i18n support
src/components/: Reusable React components
src/components/ui/: Shadcn UI base components
src/i18n/: Internationalization configuration and utilities
src/lib/: Utility functions and data fetching logic
src/types/: TypeScript type definitions
content/: Blog posts in MDX format (organized by locale)
messages/: i18n translation JSON files
public/: Static assets (images, fonts, etc.)
e2e/: End-to-end tests with Playwright

📦 Tech Stack

Core Package

Next.js - React framework
React - UI library
TypeScript - Type safety

Styling Toolkit

Tailwind CSS - Utility-first CSS framework
Shadcn UI - Component library
Motion - Animation library
Lucide React - Icon library
Simple Icons - Brand icons

Content Helper

next-mdx-remote - MDX support
next-intl - Internationalization
Shiki - Syntax highlighting
Sandpack - Live code editor
KaTeX - Math rendering
remark - Markdown processing
rehype - HTML processing

Testing Library

Vitest - Unit testing
Playwright - E2E testing
Testing Library - React testing

Development Tool

ESLint - Linting
Stylelint - CSS linting
Prettier - Code formatting
pnpm - Package manager

🚧 Caveats

import and export statements cannot be used inside MDX files due to next-mdx-remote limitations.
If you need custom components in MDX, add them to src/components/post-content.tsx.
See explanation for details.

Name		Name	Last commit message	Last commit date
Latest commit History 2,292 Commits
.claude		.claude
.github		.github
__tests__		__tests__
content		content
e2e		e2e
messages		messages
public		public
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.prettierrc.json		.prettierrc.json
.stylelintrc.json		.stylelintrc.json
.versionrc.json		.versionrc.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
codecov.yml		codecov.yml
components.json		components.json
eslint.config.mjs		eslint.config.mjs
giscus.json		giscus.json
next.config.ts		next.config.ts
package.json		package.json
playwright.config.ts		playwright.config.ts
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vitest.config.mts		vitest.config.mts

License

sabertazimi/blog

Folders and files

Latest commit

History

Repository files navigation

Next.js Blog Starter

✨ Features

Content & UX

LLM-Ready

Developer Experience

📑 Post Template

🚀 Quick Start

Prerequisites

Installation

Development

Build

🌠 Deployment

🔧 Configuration

Site Configuration

i18n Configuration

Theme Customization

Shadcn UI Registries

MDX Components

📂 Project Structure

Key Directories

📦 Tech Stack

Core Package

Styling Toolkit

Content Helper

Testing Library

Development Tool

🚧 Caveats

🔖 Contact

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 40

Packages 0

Uh oh!

Contributors 9

Uh oh!

Languages

Packages