Next.js Blog Starter

An awesome blog system based on Next.js.

Default	Nature

✨ Features

Visual Features

Modern Landing Page
- Animated typing effect for title with morphing text
- Gravity stars background animation
- Flickering grid effects
- Smooth page transitions with View Transitions API
Beautiful Post Cards
- Optimized image loading with Next.js Image
- Dot pattern placeholders for loading states
- Reading time estimation
- Search posts with command menu (⌘K)
Advanced Tag System
- Separate pages for posts under each tag
- Tag filtering with command menu (⌘K)
Rich MDX Support
- Optimized vertical rhythm for typography
- Custom styled components for Markdown elements
- GitHub Flavored Markdown (GFM) support
- KaTeX math rendering support
- Admonition containers (note, tip, warning, danger, etc.)
- Emoji shortcodes support (:smile: → 😄)
- Image preview with optimized loading
- Beautiful code blocks powered by Shiki:
  - Dual theme support (light/dark mode)
  - Syntax highlighting for 200+ languages
  - Line numbers support
  - Line highlighting support
  - Custom code title support
  - One-click code copy button
- Live code editor powered by Sandpack:
  - Interactive React/TypeScript playground
  - Real-time preview
  - Multi-file support
  - Hot module reloading
- Advanced Table of Contents (TOC):
  - Automatic heading extraction from MDX content
  - Active section tracking with IntersectionObserver
  - Smooth scroll with visual progress indicator
  - Collapsible mobile TOC with progress circle
  - Hierarchical structure with depth-based indentation
  - Auto-scroll to active item in viewport
- Automatic navigation generation:
  - Previous/next post navigation
  - Auto-linked headings with anchor links
GitHub Integration
- GitHub profile card with stats
- Repository information cards
Social Features
- Disqus comments system
- Share buttons for X, Facebook, and Weibo
User Experience
- Dark mode support with smooth transitions
- Customized 404 not found page
- Back to top button
- Progress bar for page navigation
- Mobile-first responsive design
- Command menu for quick navigation (⌘K)
- Smooth animations powered by Motion
Internationalization (i18n)
- Full i18n support powered by next-intl
- Bilingual support: English (en-US) and Chinese (zh-CN)
- Language switcher with locale-specific routing
- Localized content for posts and UI elements
- SEO-friendly locale URLs

Development Features

Modern Tech Stack
- Next.js with App Router and Turbopack
- React with React Compiler enabled
- TypeScript with strict mode
- Tailwind CSS with custom CSS variables
- Shadcn UI component library
- pnpm for fast package management
Code Quality
- ESLint with Flat Config
- Stylelint for CSS linting
- Prettier with Tailwind CSS plugin
- TypeScript strict type checking
Testing
- Vitest for unit testing with coverage
- Playwright for E2E testing (Chrome, Firefox, Safari)
- Testing Library for React component testing
Performance
- Lightning fast HMR with Turbopack
- Optimized builds with Rust compiler
- Automatic code splitting
- Image optimization with Next.js Image
SEO
- Meta tags optimization
- Automatic sitemap generation
- robots.txt support
- Open Graph support
- Twitter Card support
Developer Experience
- Hot module reloading
- Dynamic route generation for Markdown posts
- Separate components for everything
- Fully customizable through Tailwind CSS
- Out of box support for Vercel deployment
- Git-based post update time tracking

📑 Post Template

.yaml front matter + .mdx body:

---
layout: post
title: 'React Redux Basic Notes'
description: 'Daily I learned'
author: 'sabertaz'
date: 2022-02-03
thumbnail: '/photos/pen-writing-on-notebook.jpg'
tags:
  - Redux
  - React
  - JavaScript
  - Frontend Development
  - Web Development
---

# React Redux Basic Notes

## 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

Testing

# Run unit tests in watch mode
pnpm test

# Run unit tests with coverage
pnpm test:all

# Run E2E tests
pnpm e2e

# View E2E test report
pnpm e2e:report

Linting

# Run all linters
pnpm lint

# Run ESLint and Stylelint
pnpm lint:style

# Run TypeScript type checking
pnpm lint:type-check

# Auto-fix linting issues
pnpm lint:fix

🌠 Deployment

Build for production:

pnpm build

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

📂 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
├── contents/                      # 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/
│   ├── photos/
│   └── ...
├── 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
contents/: 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

🔧 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 contents/[locale]/:

contents/
├── 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 example:

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/nature.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
}

📦 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,247 Commits
.claude		.claude
.cursor/rules		.cursor/rules
.github		.github
__tests__		__tests__
contents		contents
e2e		e2e
messages		messages
public		public
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.mcp.json		.mcp.json
.prettierrc.json		.prettierrc.json
.stylelintrc.json		.stylelintrc.json
.tokeignore		.tokeignore
.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
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

Visual Features

Development Features

📑 Post Template

🚀 Quick Start

Prerequisites

Installation

Development

Build

Testing

Linting

🌠 Deployment

📂 Project Structure

Key Directories

🔧 Configuration

Site Configuration

i18n Configuration

Theme Customization

Shadcn UI Registries

MDX Components

📦 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 38

Packages 0

Uh oh!

Contributors 9

Uh oh!

Languages

Packages