# Firefly
> A Fresh and Beautiful Astro Blog Theme Template
>
> 
>
> [](https://github.com/CuteLeaf/Firefly/stargazers)
[](https://github.com/CuteLeaf/Firefly/network/members)
[](https://github.com/CuteLeaf/Firefly/issues)
>
> 
[](https://deepwiki.com/CuteLeaf/Firefly)
[](https://afdian.com/a/cuteleaf)
---
๐ Quick Guide:
[**๐ฅ๏ธLive Demo**](https://firefly.cuteleaf.cn/) /
[**๐Documentation**](https://docs-firefly.cuteleaf.cn/) /
[**๐My Blog**](https://blog.cuteleaf.cn)
๐ README:
**[็ฎไฝไธญๆ](README.md)** | **[็น้ซไธญๆ](docs/README.zh-TW.md)** | **[English](README.en.md)** | **[ๆฅๆฌ่ช](docs/README.ja.md)** | **[ะ ัััะบะธะน](docs/README.ru.md)**
โก Static Site Generation: Ultra-fast loading speed and SEO optimization based on Astro
๐จ Modern Design: Clean and beautiful interface with customizable theme colors
๐ฑ Mobile-Friendly: Perfect responsive experience with mobile-specific optimizations
๐ง Highly Configurable: Most features can be customized through configuration files
>[!TIP]
>In important layouts, Firefly innovatively adds dual sidebars, article grid (multi-column) layout, masonry layout,
>
>Includes site statistics, calendar component, table of contents and other widgets to enrich the sidebar,
>
>While also retaining fuwari layout system, freely switchable in the configuration file.
>
>**For more layout configurations and demos, please see: [Firefly Layout System Details](https://firefly.cuteleaf.cn/posts/firefly-layout-system/)**
## โจ Features
### Core Features
- [x] **Astro + Tailwind CSS** - Ultra-fast static site generation based on modern tech stack
- [x] **Smooth Animations** - Swup page transition animations for silky smooth browsing experience
- [x] **Responsive Design** - Perfect adaptation for desktop, tablet and mobile devices
- [x] **Multi-language Support** - i18n internationalization, supports Simplified Chinese, Traditional Chinese, English, Japanese, Russian
- [x] **Full-text Search** - Client-side search based on Pagefind, supports article content indexing. Also supports MeiliSearch search engine
### Personalization
- [x] **Sidebar** - Supports single sidebar, dual sidebar configuration, freely switchable in frontend
- [x] **Article Layout** - Supports list (single column) and grid (multi-column/masonry) layout, freely switchable in frontend
- [x] **Font Management** - Custom font support with rich font selector
- [x] **Footer Configuration** - HTML content injection, fully customizable
- [x] **Navbar Customization** - Logo, title, links fully customizable
- [x] **Wallpaper Mode Switching** - Banner wallpaper, fullscreen wallpaper, solid background, freely switchable in frontend
- [x] **Theme Color Customization** - 360ยฐ hue adjustment, supports light/dark/system three modes, freely switchable in frontend
### Page Components
- [x] **Guestbook** - Supports guestbook page with integrated comment system
- [x] **Announcement Bar** - Top announcement notification, supports closing and custom styles
- [x] **Mascot** - Supports both Spine and Live2D animation engines
- [x] **Site Statistics** - Displays article, category, tag counts, total word count, running time, last update time
- [x] **Site Calendar** - Displays current month calendar and published articles for the month
- [x] **Sponsor Page** - Multiple payment methods, payment QR codes, sponsor list, in-article sponsor button
- [x] **Share Poster** - Supports generating beautiful article share posters containing article summary, QR code, etc.
- [x] **Sakura Effect** - Supports sakura effect, fullscreen sakura animation
- [x] **Friend Links** - Beautiful friend link display cards
- [x] **Ad Component** - Supports custom sidebar advertising content
- [x] **Bangumi** - Display anime and game tracking based on Bangumi API
- [x] **Comment System** - Integrates Twikoo, Waline, Giscus, Disqus, Artalk comment systems
- [x] **Visit Counter** - Supports calling Waline, Twikoo built-in visit tracking
- [x] **Music Player** - Based on APlayer, supports local music and Meting API online music
### Content Enhancement
- [x] **Image Lightbox** - Fancybox image preview functionality
- [x] **Floating TOC** - Dynamically displays article table of contents, supports anchor jumping, shown when sidebar TOC is hidden
- [x] **Email Protection** - Prevent automated crawlers from directly scraping email addresses to avoid spam
- [x] **Sidebar TOC** - Dynamically displays article table of contents, supports anchor jumping
- [x] **Enhanced Code Blocks** - Based on Expressive Code, supports code folding, line numbers, language identification
- [x] **Math Formula Support** - KaTeX rendering engine, supports inline and block formulas
- [x] **Markdown Extensions** - [Markdown extended features](https://github.com/saicaca/fuwari?tab=readme-ov-file#-markdown-extended-syntax), also includes [Admonitions](https://firefly.cuteleaf.cn/posts/markdown-extended/#%E6%8F%90%E9%86%92%E6%A1%86), [GitHub repository cards](https://firefly.cuteleaf.cn/posts/markdown-extended/#github-%E4%BB%93%E5%BA%93%E5%8D%A1%E7%89%87), [Expressive Code](http://firefly.cuteleaf.cn/posts/code-examples/)
- [x] **Random Cover Images** - Supports fetching random cover images via API
### SEO
- [x] **SEO Optimization** - Complete meta tags and structured data
- [x] **RSS Feed** - Automatically generates RSS Feed
- [x] **Sitemap** - Automatically generates XML Sitemap with page filtering configuration
## ๐ Planned...
- [ ] **Refactor Live2D Mascot**
- [ ] **Continuous Animation Smoothness Optimization**
- [ ] More features in continuous development...
If you have useful features and optimizations, please submit a [Pull Request](https://github.com/CuteLeaf/Firefly/pulls)
## ๐ Quick Start
### Requirements
- Node.js โค 22
- pnpm โค 9
### Local Development
1. **Clone the repository:**
```bash
git clone https://github.com/Cuteleaf/Firefly.git
cd Firefly
```
**First [Fork](https://github.com/CuteLeaf/Firefly/fork) to your own repository then clone (recommended)**
```bash
git clone https://github.com/you-github-name/Firefly.git
cd Firefly
```
3. **Install dependencies:**
```bash
# Install pnpm if not installed
npm install -g pnpm
# Install project dependencies
pnpm install
```
4. **Configure blog:**
- Edit configuration files in `src/config/` directory to customize blog settings
5. **Start development server:**
```bash
pnpm dev
```
Blog will be available at `http://localhost:4321`
### Platform Hosting Deployment
- **Refer to the [official guide](https://docs.astro.build/en/guides/deploy/) to deploy your blog to Vercel, Netlify, GitHub Pages, Cloudflare Pages, EdgeOne Pages, etc.**
Framework Preset: `Astro`
Root Directory: `./`
Output Directory: `dist`
Build Command: `pnpm run build`
Install Command: `pnpm install`
## ๐ Configuration
> ๐ **Detailed Configuration Documentation**: Check [Firefly Documentation](https://docs-firefly.cuteleaf.cn/) for complete configuration guide
### Setting Website Language
To set the default language for your blog, edit the `src/config/siteConfig.ts` file:
```typescript
// Define site language
const SITE_LANG = "zh_CN";
```
**Supported language codes:**
- `zh_CN` - Simplified Chinese
- `zh_TW` - Traditional Chinese
- `en` - English
- `ja` - Japanese
- `ru` - Russian
### Configuration File Structure
```
src/
โโโ config/
โ โโโ index.ts # Configuration index file
โ โโโ siteConfig.ts # Site basic configuration
โ โโโ backgroundWallpaper.ts # Background wallpaper configuration
โ โโโ profileConfig.ts # User profile configuration
โ โโโ commentConfig.ts # Comment system configuration
โ โโโ announcementConfig.ts # Announcement configuration
โ โโโ licenseConfig.ts # License configuration
โ โโโ footerConfig.ts # Footer configuration
โ โโโ FooterConfig.html # Footer HTML content
โ โโโ expressiveCodeConfig.ts # Code highlighting configuration
โ โโโ sakuraConfig.ts # Sakura effect configuration
โ โโโ fontConfig.ts # Font configuration
โ โโโ sidebarConfig.ts # Sidebar layout configuration
โ โโโ navBarConfig.ts # Navbar configuration
โ โโโ musicConfig.ts # Music player configuration
โ โโโ pioConfig.ts # Mascot configuration
โ โโโ adConfig.ts # Ad configuration
โ โโโ friendsConfig.ts # Friend links configuration
โ โโโ sponsorConfig.ts # Sponsor configuration
โ โโโ coverImageConfig.ts # Article cover image configuration
```
## โ๏ธ Article Frontmatter
```yaml
---
title: My First Blog Post
published: 2023-09-09
description: This is the first post of my new Astro blog.
image: ./cover.jpg # Or use "api" to enable random cover images
tags: [Foo, Bar]
category: Front-end
draft: false
lang: zh-CN # Only set when article language differs from site language in `siteConfig.ts`
---
```
## ๐ง Commands
All commands need to be executed in the project root directory:
| Command | Action |
|:---------------------------|:----------------------------------------------------|
| `pnpm install` | Install dependencies |
| `pnpm dev` | Start local development server at `localhost:4321` |
| `pnpm build` | Build site to `./dist/` |
| `pnpm preview` | Preview built site locally |
| `pnpm check` | Check for errors in code |
| `pnpm format` | Format your code using Biome |
| `pnpm new-post ` | Create new article |
| `pnpm astro ...` | Execute `astro add`, `astro check` and other commands |
| `pnpm astro --help` | Display Astro CLI help |
## ๐ Acknowledgments
- Special thanks to [saicaca](https://github.com/saicaca) for developing the [Fuwari](https://github.com/saicaca/fuwari) template, which Firefly is based on
- Referenced blogger [Kasuka](https://kasuha.com)'s [Bangumi Collection Display](https://kasuha.com/posts/fuwari-enhance-ep2/) and [Email Protection/Image Title](https://kasuha.com/posts/fuwari-enhance-ep1/) solutions
- Referenced [Mizuki](https://github.com/matsuzaka-yuki/Mizuki)'s banner title, multi-level menu navbar, sakura effect, KaTeX, and Fancybox solutions
- Built with [Astro](https://astro.build) and [Tailwind CSS](https://tailwindcss.com)
- Uses [MetingJS](https://github.com/metowolf/MetingJS) and [APlayer](https://github.com/MoePlayer/APlayer) music player
- Uses Chibi `Firefly` mascot spine model provided by Bilibili creator [ๅ
ฌๅ
ฌ็ๆฅๅธธ](https://space.bilibili.com/3546750017080050)
- Icons from [Iconify](https://iconify.design/)
- Firefly-related image assets are copyrighted by [miHoYo](https://www.mihoyo.com/), the developer of ["Honkai: Star Rail"](https://sr.mihoyo.com/).
## ๐ License
This project is licensed under the [MIT license](https://mit-license.org/). See the [LICENSE](./LICENSE) file for details.
**Copyright Notice:**
- Copyright (c) 2024 [saicaca](https://github.com/saicaca) - [fuwari](https://github.com/saicaca/fuwari)
- Copyright (c) 2025 [CuteLeaf](https://github.com/CuteLeaf) - [Firefly](https://github.com/CuteLeaf/Firefly)
Under the MIT license, you are free to use, modify, and distribute the code, but you must retain the above copyright notice.
## ๐ Contributors
Thanks to the following contributors for their contributions to this project. If you have any questions or suggestions, please submit an [Issue](https://github.com/CuteLeaf/Firefly/issues) or [Pull Request](https://github.com/CuteLeaf/Firefly/pulls).
## โญ Star History
[](https://star-history.com/#CuteLeaf/Firefly&Date)