# Mizuki
A modern, feature-rich static blog template built with Astro, enhanced with advanced functionality and beautiful design.
## Features
### Design & UI
- Built with Astro and Tailwind CSS
- Smooth animations and page transitions with Swup
- Light / dark mode with system preference detection
- Customizable theme colors & dynamic banner carousel
- Fully responsive design for all devices
- Beautiful typography with JetBrains Mono font
### Content & Search
- Advanced search functionality with Pagefind
- Enhanced Markdown features with syntax highlighting
- Interactive table of contents with auto-scroll
- RSS feed generation
- Reading time estimation
- Post categorization and tagging
### Internationalization
- Multi-language support with real-time translation
- Auto language detection based on user preferences
- Client-side translation powered by Edge Translate
- Support for 10+ languages (EN, ZH-CN, ZH-TW, JA, KO, ES, TH, VI, ID, TR)
### Special Pages
- Anime Tracking Page - Track your anime watching progress with ratings
- Friends Links Page - Showcase your friend's websites with beautiful cards
- Diary/Moments Page - Share life moments like social media posts
- Archive Page - Organized post timeline view
- About Page - Customizable personal introduction
### Technical Features
- Enhanced Code Blocks with Expressive Code
- Math Support with KaTeX rendering
- Image Optimization with PhotoSwipe gallery
- SEO Optimized with sitemap and meta tags
- Performance Optimized with lazy loading and caching
- Comment System integration ready (Twikoo)
## Getting Started
### Installation
1. Clone the repository:
```
git clone https://github.com/your-username/mizuki.git
cd mizuki
```
2. Install dependencies:
```
# Install pnpm if you haven't
npm install -g pnpm
# Install project dependencies
pnpm install
```
3. Configure your blog:
- Edit `src/config.ts` to customize your blog settings
- Update site information, theme colors, banner images, and social links
- Configure translation settings and special page features
4. Start development server:
```
pnpm dev
```
Your blog will be available at `http://localhost:4321`
### Content Management
- Create a new post: `pnpm new-post <filename>`
- Edit posts: Modify files in `src/content/posts/`
- Customize pages: Edit special pages in `src/content/spec/`
- Add images: Place images in `src/assets/` or `public/`
### Deployment
Deploy your blog to any static hosting platform:
- Vercel: Connect your GitHub repository to Vercel
- Netlify: Deploy directly from GitHub
- GitHub Pages: Use the included GitHub Actions workflow
- Cloudflare Pages: Connect your repository
Before deployment, update the `site` URL in `astro.config.mjs`.
## Post Frontmatter
```
---
title: My First Blog Post
published: 2023-09-09
description: This is the first post of my new Astro blog.
image: ./cover.jpg
tags: [Foo, Bar]
category: Front-end
draft: false
pinned: false
---
```
### Frontmatter Fields
- title: Post title (required)
- published: Publication date (required)
- description: Post description for SEO and previews
- image: Cover image path (relative to post file)
- tags: Array of tags for categorization
- category: Post category
- draft: Set to `true` to hide post in production
- pinned: Set to `true` to pin post to top of the list
### Pinned Posts
The `pinned` field allows you to pin important posts to the top of your blog. Pinned posts will always appear before regular posts, regardless of their publication date.
Usage:
```
pinned: true # Pin this post to the top
pinned: false # Regular post (default)
```
Sorting behavior:
1. Pinned posts appear first, sorted by publication date (newest first)
2. Regular posts follow, sorted by publication date (newest first)
```
lang: jp # Set only if the post's language differs from the site's language in `config.ts`
---
```
## Markdown Extended Syntax
Mizuki supports enhanced Markdown features beyond standard GitHub Flavored Markdown:
### Enhanced Writing
- Admonitions: Create beautiful callout boxes with `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, etc.
- Math Equations: Write LaTeX math with `$inline$` and `$$block$$` syntax
- Code Highlighting: Advanced syntax highlighting with line numbers and copy buttons
- GitHub Cards: Embed repository cards with `::github{repo="user/repo"}`
### Visual Elements
- Image Galleries: Automatic PhotoSwipe integration for image viewing
- Collapsible Sections: Create expandable content blocks
- Custom Components: Use special directives for enhanced content
### Content Organization
- Table of Contents: Auto-generated from headings with smooth scrolling
- Reading Time: Automatic calculation and display
- Post Metadata: Rich frontmatter support with categories and tags
## Commands
All commands are run from the root of the project:
| Command | Action |
|:---------------------------|:----------------------------------------------------|
| `pnpm install` | Install dependencies |
| `pnpm dev` | Start local dev server at `localhost:4321` |
| `pnpm build` | Build production site to `./dist/` |
| `pnpm preview` | Preview build locally before deploying |
| `pnpm check` | Run Astro checks for errors |
| `pnpm format` | Format code using Biome |
| `pnpm lint` | Lint and fix code issues |
| `pnpm new-post <filename>` | Create a new blog post |
| `pnpm astro ...` | Run Astro CLI commands |
## Configuration Guide
### Basic Configuration
Edit `src/config.ts` to customize your blog:
```
export const siteConfig: SiteConfig = {
title: "Your Blog Name",
subtitle: "Your Blog Description",
lang: "en", // or "zh-CN", "ja", etc.
themeColor: {
hue: 210, // 0-360, theme color hue
fixed: false, // hide theme color picker
},
translate: {
enable: true, // enable translation feature
service: "client.edge", // translation service
defaultLanguage: "chinese_simplified",
},
banner: {
enable: true,
src: ["assets/banner/1.webp"], // banner images
carousel: {
enable: true,
interval: 0.8, // seconds
},
},
};
```
### Special Pages Configuration
- Anime Page: Edit anime list in `src/pages/anime.astro`
- Friends Page: Edit friends data in `src/content/spec/friends.md`
- Diary Page: Edit moments in `src/pages/diary.astro`
- About Page: Edit content in `src/content/spec/about.md`
## Contributing
We welcome contributions! Please feel free to submit issues and pull requests.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgments
- Based on the original Fuwari template
- Built with Astro and Tailwind CSS
- Inspired by Yukina - A beautiful and elegant blog template
- Translation powered by translate - AI i18n solution for automatic HTML translation
- Icons from Iconify
### Special Thanks
- Yukina - For providing inspiration and design ideas that helped shape this project. Yukina is an elegant blog template that demonstrates excellent design principles and user experience.
- translate - For providing an innovative AI-powered i18n solution that enables automatic HTML translation with just two lines of JavaScript. This open-source tool makes multi-language support incredibly simple and efficient.
If you find this project helpful, please consider giving it a star!
