README.md

metadata

title: Firefly Admin Blog
sdk: docker
app_port: 7860

Firefly

A Fresh and Beautiful Astro Static Blog Theme Template

---

📖 README: 简体中文 | 繁體中文 | English | 日本語 | Русский

🚀 Quick Guide: 🖥️Live Demo / 📝Documentation / 🍀My Blog

⚡ 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

Firefly is a fresh and beautiful personal blog theme template based on the Astro framework and the Fuwari template, designed for tech enthusiasts and content creators. This theme integrates modern web technology stacks, provides rich functional modules and highly customizable interfaces, allowing you to easily create a professional and beautiful personal blog website.

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 the original fuwari layout, which can be freely switched in the configuration file according to your preferences.

For more layout configurations and demos, please see: Firefly Layout System Details

Firefly supports i18n multi-language switching, but except for Simplified Chinese, other languages are AI-translated. If there are any errors, welcome to submit Pull Request for correction.

✨ Features

Core Features

• Astro + Tailwind CSS - Ultra-fast static site generation based on modern tech stack
• Smooth Animations - Swup page transition animations for silky smooth browsing experience
• Responsive Design - Perfect adaptation for desktop, tablet and mobile devices
• Multi-language Support - i18n internationalization, supports Simplified Chinese, Traditional Chinese, English, Japanese, Russian
• Full-text Search - Client-side search based on Pagefind, supports article content indexing.

Personalization

• Dynamic Sidebar - Supports single sidebar, dual sidebar configuration
• Article Layout - Supports list (single column) and grid (multi-column/masonry) layout
• Font Management - Custom font support with rich font selector
• Footer Configuration - HTML content injection, fully customizable
• Light/Dark Mode - Supports light/dark/system three modes
• Navbar Customization - Logo, title, links fully customizable
• Wallpaper Mode Switching - Banner wallpaper, fullscreen wallpaper, solid background
• Theme Color Customization - 360° hue adjustment

Page Components

• Guestbook - Supports guestbook page
• Announcement Bar - Supports sidebar announcement notification
• Mascot - Supports both Spine and Live2D animation engines
• Site Statistics - Displays article, category, tag counts, total word count, etc.
• Site Calendar - Displays current month calendar and published articles for the month
• Sponsor Page - Sponsor link redirection, payment QR codes display, sponsor list, in-article sponsor button
• Share Poster - Supports generating beautiful article share posters
• Sakura Effect - Supports sakura effect, fullscreen sakura animation
• Friend Links - Beautiful friend links display page
• Ad Component - Supports custom sidebar advertising content
• Bangumi - Display anime and game tracking based on Bangumi API
• Comment System - Integrates Twikoo, Waline, Giscus, Disqus, Artalk comment systems
• Visit Counter - Supports calling Waline, Twikoo built-in visit tracking
• Music Player - Material Design 3 style music player

Content Enhancement

• Image Lightbox - Fancybox image preview functionality
• Floating TOC - Dynamically displays article table of contents, supports anchor jumping, shown when sidebar TOC is hidden
• Email Protection - Prevent automated crawlers from directly scraping email addresses to avoid spam
• Sidebar TOC - Dynamically displays article table of contents, supports anchor jumping
• Enhanced Code Blocks - Based on Expressive Code, supports code folding, line numbers, language identification
• Math Formula Support - KaTeX rendering engine, supports inline and block formulas
• Random Cover Images - Supports fetching random cover images via API
• Markdown Extensions - More Markdown extension syntax support

SEO

• SEO Optimization - Complete meta tags and structured data
• RSS Feed - Automatically generates RSS Feed
• Sitemap - Automatically generates XML Sitemap with page filtering configuration
• Analytics - Integrates Google Analytics, Microsoft Clarity

If you have useful features and optimizations, please submit a Pull Request

🚀 Quick Start

Requirements

• Node.js ≤ 22
• pnpm ≤ 9

Local Development

1. Clone the repository:

   git clone https://github.com/Cuteleaf/Firefly.git
   cd Firefly
   

   First Fork to your own repository then clone (recommended). Don't forget to Star before Fork!

   git clone https://github.com/you-github-name/Firefly.git
   cd Firefly
   

2. Install dependencies:

   # Install pnpm if not installed
   npm install -g pnpm
   
   # Install project dependencies
   pnpm install
   

3. Configure blog:

   • Edit configuration files in src/config/ directory to customize blog settings

4. Start development server:

   pnpm dev
   

   Blog will be available at http://localhost:4321

Platform Hosting Deployment

• Refer to the official guide 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

Hugging Face Spaces (Docker Admin)

This repository can also run as a Docker Space with the built-in Firefly admin backend.

1. Create a new Hugging Face Docker Space and keep the app port set to 7860.
2. Add Space environment variables or secrets named ADMIN and PASSWORD.
3. Build and run the container from this repository. The included Dockerfile builds the Astro site and starts server/index.mjs.
4. Open /admin or /cmsadmin after deployment to log in to the admin panel.

Runtime-edited data is currently stored inside the container filesystem:

• storage/admin/config.json for editable site configuration
• src/content/posts and src/content/spec for posts and pages
• public and src/content/posts for uploaded images

This storage is temporary in Spaces until a persistent storage layer is added in a later version.

📖 Configuration

📚 Detailed Configuration Documentation: Check Firefly Documentation for complete configuration guide

Setting Website Language

To set the default language for your blog, edit the src/config/siteConfig.ts file:

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

---
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`
pinned: false    # Pin article
comment: true    # Enable comments
---

📖 Markdown Extensions

In addition to the default GitHub Flavored Markdown support in Astro, there are some additional Markdown features:

• Admonitions - Supports configuration for GitHub, Obsidian, and VitePress themes (Preview and Usage)
• GitHub Repository Cards (Preview and Usage)
• Enhanced Code Blocks based on Expressive Code (Preview / Documentation)

🧞 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 <filename>	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 for developing the fuwari template, which Firefly is based on
• Referenced blogger 霞葉's Bangumi Collection Display and Email Protection/Image Title solutions
• Referenced Mizuki's banner title, multi-level menu navbar, sakura effect, KaTeX, and Fancybox solutions
• Built with Astro and Tailwind CSS
• Uses Chibi Firefly mascot spine model provided by Bilibili creator 公公的日常
• Icons from Iconify
• Firefly-related image assets are copyrighted by miHoYo, the developer of "Honkai: Star Rail".

📝 License

This project is licensed under the MIT license. See the LICENSE file for details.

Originally forked from saicaca/fuwari. Thanks to the original author for their contributions. The original project is licensed under the MIT License

Copyright Notice:

• Copyright (c) 2024 saicaca - fuwari
• Copyright (c) 2025 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 or Pull Request.

Thanks to the following contributors for their contributions to the original project fuwari, which laid the foundation for this project.

⭐ Star History