Astro Blog Template

A modern, feature-rich personal blog template built with Astro 7 and Tailwind CSS 4 — fully static, zero client-side JavaScript by default, and easy to customize from a single config file.

English | 简体中文

🌐 Live demo: https://ruijieking.github.io

✨ Features

🌗 Dark / Light theme with FOUC (flash-of-unstyled-content) protection, remembers your choice
🖼️ Wallpaper system — separate wallpaper sets per theme, cross-fade transitions, persisted per theme
📝 Blog powered by Astro content collections (title, description, pubDate, category, tags)
📚 Archive timeline grouped by year, with instant search and multi-tag filtering
💬 Daily Talk — a lightweight microblog / short-note section
📷 Photo albums — folder-based albums with stacked covers and a lightbox viewer
📑 Table of contents auto-generated from headings on each post page
🔍 Full SEO — Open Graph, Twitter Cards, canonical URLs, and JSON-LD structured data
📡 RSS feed, sitemap, and robots.txt
✨ Scroll-in animations and frosted-glass card design
📱 Fully responsive, with a mobile hamburger menu
⚡ Optimized images out of the box (astro:assets + sharp, WebP output)
🚀 One-command deploy to GitHub Pages via GitHub Actions

�🚀 Quick Start

Prerequisites

Node.js >= 22.12.0
npm (or pnpm / yarn)

1. Install

npm install

2. Develop

Start the dev server at http://localhost:4321:

npm run dev

3. Build & Preview

npm run build     # outputs to dist/
npm run preview   # preview the production build

🎨 Customization

Everything you need to personalize the site lives in one file: src/site.config.ts. Change it once and the whole site updates automatically.

export const site = {
  name: 'My Blog',                    // site name (logo, footer, page titles, SEO)
  defaultTitle: 'My Blog',            // fallback page title
  description: 'Write code, take photos, record life.',
  url: 'https://example.com',         // your site domain
  ogImage: '/og.png',                 // social share image (public/, 1200×630)
  ogSiteName: 'My Blog',              // name shown on share cards
  author: {
    name: 'Your Name',
    github: 'your-github-username',
    location: 'Your City',
  },
  about: 'This is my personal blog, built with Astro.',
  nav: [
    { href: '/talk', label: 'Talk' },
    { href: '/blog', label: 'Blog' },
    { href: '/archive', label: 'Archive' },
    { href: '/photo', label: 'Photo' },
    { href: '/about', label: 'About' },
  ],
};

📝 Adding Content

Blog posts

Add a Markdown file to src/content/blog/:

---
title: 'Hello World'
description: 'My first post'
pubDate: '2026-01-01'
category: 'Life'          # optional
tags: ['astro', 'blog']   # optional
---

Content here…

Daily Talk

Add a Markdown file to src/content/talk/ (no title required):

---
update: '2026-01-01-12:00'
---

Short note text…

Photo albums

Create a folder inside src/assets/album/ — each folder becomes an album, and its images are displayed automatically:

src/assets/album/
├── Trip/          ← album: "Trip"
│   ├── photo1.jpg
│   └── photo2.png
└── Daily/
    └── photo3.jpg

Wallpapers

Place wallpapers in src/assets/wallpaper/:

src/assets/wallpaper/
├── light/         ← wallpapers shown in light theme
└── dark/          ← wallpapers shown in dark theme

A file named 默认light.png / 默认dark.png (or the first file in each folder) is used as the default wallpaper.

🗂️ Project Structure

├── public/                 # static assets (favicon, og.png)
├── src/
│   ├── assets/
│   │   ├── album/          # photo albums (folder = album)
│   │   └── wallpaper/      # theme wallpapers (light/ dark/)
│   ├── components/         # UI components
│   ├── content/
│   │   ├── blog/           # blog posts (.md)
│   │   └── talk/           # daily talk notes (.md)
│   ├── layouts/            # BaseLayout (theme, wallpapers, SEO)
│   ├── pages/              # routes
│   ├── styles/global.css   # Tailwind entry
│   ├── content.config.ts   # content collection schemas
│   └── site.config.ts      # ⭐ global site config
├── astro.config.mjs
├── package.json
└── tsconfig.json

🚢 Deployment

GitHub Pages (recommended)

The included workflow at .github/workflows/deploy.yml builds and deploys automatically on every push to main:

Push this template to a GitHub repository.
Go to Settings → Pages and set the source to GitHub Actions.
Done — every push to main now rebuilds and redeploys.

Other platforms

This is a static site — run npm run build and deploy the dist/ folder to any host:

Netlify: build command npm run build, publish directory dist
Vercel: framework preset Astro
Cloudflare Pages: build command npm run build, output directory dist

💡 Set site.url in src/site.config.ts to your production domain for correct canonical URLs, sitemap, and robots.txt.

🛠️ Tech Stack

Tool	Purpose
Astro 7	Static site framework
Tailwind CSS 4	Styling (`@tailwindcss/vite`)
@tailwindcss/typography	Post typography
astro:assets + sharp	Image optimization
@astrojs/sitemap	Sitemap generation
@astrojs/rss	RSS feed

Example