This document provides a high-level introduction to Firefly, an Astro-based blog theme template designed for technical writers and content creators. It explains the system's architecture, core technologies, key subsystems, and how they interact to generate a static blog website.
For detailed information on specific subsystems:
Firefly is a feature-rich, highly customizable static blog theme for Astro 5.16.8, built on the fuwari template foundation. It is designed for technical enthusiasts and content creators who want a professional blog with advanced layout capabilities and extensive customization options.
Built With:
Key Characteristics:
Extensions Over Fuwari: Firefly innovatively adds dual sidebars, multi-column grid layouts, waterfall (masonry) view, 8+ widget types, enhanced configuration system, and mobile-specific optimizations while retaining fuwari's clean design philosophy.
Sources: README.md7-44 README.md55-106 package.json1-89 src/types/config.ts1-719
Firefly's architecture is organized around four primary subsystems (by importance score):
| Subsystem | Importance | Key Components | Purpose |
|---|---|---|---|
| Configuration System | 148.39 | siteConfig.ts, 20+ config files, types/config.ts | Declarative control of all features |
| Layout System | 148.39 | Layout.astro, MainGridLayout.astro, responsive utilities | Two-tier HTML structure with grid system |
| Content Pipeline | 126.73 | Content collections, remark/rehype plugins, Expressive Code | Markdown → HTML transformation |
| Feature Systems | Variable | i18n, theme, widgets, comments, search | Modular functionality plugins |
Diagram: Four-Pillar Architecture with Code Entity Mapping
Configuration-Driven Design:
SiteConfig interface implementationTwo-Tier Layout System:
<head> management, inline theme scripts, analytics integration, and global effectsProcessing Pipeline:
Modular Feature Integration:
localStorage persistencepagefind --site dist package.json9Sources: src/config/index.ts src/types/config.ts1-719 src/layouts/Layout.astro1-1015 src/layouts/MainGridLayout.astro1-465 src/utils/responsive-utils.ts package.json9
| Technology | Version | Role in Codebase |
|---|---|---|
| Astro | 5.16.8 | Static site generator (astro.config.mjs), content collections API (getCollection()), file-based routing in src/pages/ |
| TypeScript | 5.9.2 | Type definitions in src/types/config.ts1-719 configuration validation, tsconfig.json strict mode |
| Vite | (via Astro) | Asset bundling, code splitting, dev server HMR |
| pnpm | 9.14.4 | Package manager enforced via preinstall script package.json16 |
| Technology | Version | Role in Codebase |
|---|---|---|
| Tailwind CSS | 3.4.19 | Utility classes, responsive breakpoints, tailwind.config.mjs customization |
| Svelte | 5.46.1 | Interactive components with client:load directive (Search, DisplaySettings, theme switches) |
| @tailwindcss/typography | 0.5.16 | Prose styling for markdown content package.json38 |
| Technology | Version | Role in Codebase |
|---|---|---|
| remark-math | 6.0.0 | Parse LaTeX math syntax in markdown astro.config.mjs132 |
| rehype-katex | 7.0.1 | Render math formulas with KaTeX astro.config.mjs143 |
| remark-directive | 3.0.1 | Custom directive syntax (::: callout) astro.config.mjs136 |
| rehype-slug | 6.0.0 | Generate heading IDs for anchor links astro.config.mjs144 |
| Expressive Code | 0.41.5 | Code block rendering in src/config/expressiveCodeConfig.ts |
| rehype-callouts | 2.1.2 | Admonition blocks styled per siteConfig.rehypeCallouts.theme src/config/siteConfig.ts86-88 |
Custom Plugins:
remark-reading-time.mjs, remark-excerpt.js, remark-mermaid.js (src/plugins/)rehype-figure.mjs, rehype-email-protection.mjs, rehype-components.mjs (src/plugins/)| Technology | Version | Role in Codebase |
|---|---|---|
| Pagefind | 1.4.0 | Post-build search indexing: pagefind --site dist package.json9 |
| Swup | @swup/astro 1.7.0 | SPA transitions configured in astro.config.mjs44-64 |
| Fancybox | @fancyapps/ui 6.1.7 | Image lightbox in src/components/features/FancyboxManager.astro |
| APlayer | (via CDN) | Music player configured in src/config/musicConfig.ts |
| Sharp | 0.34.5 | Image optimization for cover images and assets |
| Tool | Version | Purpose |
|---|---|---|
| Biome | 2.3.11 | Linting (pnpm lint) and formatting (pnpm format) package.json14-15 |
| @astrojs/check | 0.9.6 | Type checking Astro components (pnpm check) package.json8 |
Sources: package.json18-86 astro.config.mjs1-203 src/config/siteConfig.ts86-88
Diagram: Project Directory Structure
| Directory | Purpose | Key Files |
|---|---|---|
src/config/ | Configuration modules | siteConfig.ts, navBarConfig.ts, sidebarConfig.ts, 15+ others |
src/content/ | Content collections | posts/, spec/, content.config.ts |
src/layouts/ | Layout components | Layout.astro, MainGridLayout.astro, PostPage.astro |
src/components/ | Reusable UI components | Navbar, Sidebar widgets, PostCard, etc. |
src/pages/ | Route pages and API endpoints | [...slug].astro, api/calendar.json.ts |
src/styles/ | CSS modules | main.css, variables-unified.styl, component styles |
src/utils/ | Helper functions | Settings management, theme utilities, i18n |
src/types/ | TypeScript definitions | config.ts (706 lines of type definitions) |
src/i18n/ | Internationalization | Language files for 5 languages |
src/plugins/ | Custom plugins | Remark/Rehype extensions for markdown processing |
public/ | Static assets | Images, fonts, favicon, etc. |
Sources: README.md187-212 src/config/siteConfig.ts1-145 src/types/config.ts1-706
Diagram: Configuration Flow and Type Safety
Type-Safe Design:
types/config.ts (706 lines)SiteConfig type defines core settings src/types/config.ts10-89NavBarConfig, SidebarLayoutConfig, CommentConfig, FontConfig, etc.Modular Organization:
siteConfig.ts contains site metadata, theme colors, feature flags src/config/siteConfig.ts8-145config/index.ts aggregates all configurationsKey Configuration Files:
| Config File | Type | Purpose |
|---|---|---|
siteConfig.ts | SiteConfig | Site metadata, theme, pagination, analytics |
navBarConfig.ts | NavBarConfig | Navigation links, dropdown menus |
sidebarConfig.ts | SidebarLayoutConfig | Widget ordering, sidebar position, responsive behavior |
fontConfig.ts | FontConfig | Font library with preload support |
commentConfig.ts | CommentConfig | 5 comment providers (Twikoo, Waline, Giscus, Disqus, Artalk) |
backgroundWallpaper.ts | BackgroundWallpaperConfig | Banner/overlay/none modes, navbar transparency |
Configuration Example:
The SiteConfig type src/types/config.ts10-89 includes:
title, subtitle, site_url - Basic site informationthemeColor.hue (0-360) - Theme customization with color pickerpages object - Feature flags for sponsor/guestbook/bangumi pagespostListLayout - Grid/list/masonry layout configurationpagination.postsPerPage - Content pagination settingsSources: src/config/siteConfig.ts1-145 src/types/config.ts1-706 astro.config.mjs20-203
Firefly transforms markdown content through a sophisticated multi-stage pipeline:
Diagram: Markdown Processing Pipeline
Stage 1: Content Collection Schema
content.config.tstitle, published, description, tags, category, draft, pinned, commentBlogPostData type definition src/types/config.ts209-223Stage 2: Remark Plugins (Markdown AST)
remarkMath - Parse LaTeX math notationremarkReadingTime - Calculate reading duration from content src/plugins/remark-reading-time.mjsremarkExcerpt - Extract post summary src/plugins/remark-excerpt.jsremarkGithubAdmonitionsToDirectives - Convert GitHub-style admonitionsremarkDirective - Parse custom directive syntaxremarkSectionize - Wrap sections for stylingremarkMermaid - Process Mermaid diagrams src/plugins/remark-mermaid.jsStage 3: Rehype Plugins (HTML AST)
rehypeKatex - Render KaTeX math formulas with mhchem support astro.config.mjs143rehypeSlug - Add IDs to headings for anchor linksrehypeFigure - Wrap images in figure elements with captions src/plugins/rehype-figure.mjsrehypeEmailProtection - Obfuscate email addresses (base64/rot13) astro.config.mjs147rehypeComponents - Render custom components (GitHub cards, admonitions) astro.config.mjs148-160rehypeAutolinkHeadings - Add anchor links to headings astro.config.mjs162-183Plugin Configuration:
Sources: astro.config.mjs131-184 src/plugins/remark-reading-time.mjs src/plugins/remark-excerpt.js src/plugins/rehype-figure.mjs src/plugins/rehype-email-protection.mjs
Diagram: Build and Deployment Pipeline
Development Mode (pnpm dev):
localhost:4321 package.json6pnpm check package.json8Production Build (pnpm build):
pagefind --site dist generates search index package.json9Build Configuration:
/ astro.config.mjs38siteConfig.site_url astro.config.mjs36dist/ (default)Deployment Targets:
Astro./distpnpm run buildpnpm installSupports deployment to Vercel, Netlify, GitHub Pages, Cloudflare Pages, EdgeOne Pages README.md155-164
Development Scripts:
| Command | Purpose |
|---|---|
pnpm dev | Start dev server package.json6 |
pnpm build | Build + generate search index package.json9 |
pnpm preview | Preview built site package.json10 |
pnpm check | Astro type checking package.json8 |
pnpm format | Biome code formatting package.json14 |
pnpm lint | Biome linting package.json15 |
pnpm new-post | Scaffold new blog post package.json13 |
Sources: package.json5-16 astro.config.mjs35-203 README.md155-164
While Firefly generates static HTML, selective hydration provides interactive features:
| Component | Hydration | Purpose |
|---|---|---|
Search.svelte | client:load | Pagefind search integration in navbar |
AdvancedSearch.svelte | client:load | Full-page search interface |
DisplaySettings.svelte | client:load | Theme/wallpaper/layout controls |
LightDarkSwitch.svelte | client:load | Light/dark mode toggle |
WallpaperSwitch.svelte | client:load | Wallpaper mode cycling |
LayoutSwitchButton.svelte | client:load | Grid/list/masonry switching |
SharePoster.svelte | client:load | QR code poster generation |
Theme System:
localStorage: theme, hue, wallpaperMode siteConfig.ts34-41matchMedia APISettings Persistence:
light, dark, systembanner, overlay, nonelist, gridPage Transitions:
main, #right-sidebar-dynamic, #floating-toc-wrapper astro.config.mjs49Search System:
pagefindready eventSources: astro.config.mjs44-64 package.json9 src/config/siteConfig.ts34-41
Firefly supports 5 languages through a comprehensive i18n system:
Language Configuration:
siteConfig.ts: SITE_LANG = "zh_CN" src/config/siteConfig.ts6zh_CN, zh_TW, en, ja, ru src/types/config.ts17Translation Architecture:
i18nKey.ts - Enum with ~200 translation keysen.ts, zh_CN.ts, zh_TW.ts, ja.ts, ru.tsi18n() function - Retrieves translations by key and languagePer-Post Language Override:
lang field overrides site language README.md225Sources: src/config/siteConfig.ts6 src/types/config.ts17 README.md225
Sources: src/types/config.ts67-706 src/config/siteConfig.ts34-145 astro.config.mjs1-203
Firefly is a production-ready Astro blog theme that combines:
The system generates fully static HTML deployable to any hosting platform while maintaining interactivity through selective Svelte hydration. Its modular design allows developers to enable/disable features via configuration without touching code.
For specific implementation details, see subsequent sections of this documentation.
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.