一只喵⁹

部分新增功能使用教程

Mon, 20 Jul 2026 00:00:00 GMT

新增功能列表#

本博客已集成以下新增功能：

网站导航 - /projects/
笔记本 - /life/notebooks/
书架 - /books/
影视与游戏 - /movies-games/
更新日志 - /changelog/
日常规划 - /life/routines/
足迹 - /life/places/

1. 网站导航#

新增网站条目#

在 src/content/daohang/ 目录下创建 .md 文件：

1
---
2
name: 网站名称
3
url: https://example.com
4
description: 网站描述
5
icon: "fa7-brands:github"
6
category: 常用网站
7
order: 1
8
---

可用分类#

我的网站
常用网站
资源网站
工具网站
大佬博客
学习网站
文档
其他网站

可用图标#

使用 fa7-brands:* 格式的 FontAwesome 图标
使用 material-symbols:* 格式的 Material Symbols 图标
或使用外部图片 URL

2. 笔记本#

创建新笔记本#

在 src/content/life/notebooks/ 目录下创建文件夹，例如 my-notebook/
在文件夹内创建 _index.json 文件：

1
{
2
  "name": "我的日记本",
3
  "summary": "记录生活点滴",
4
  "cover": "cover.jpg"
5
}

在文件夹内创建 .md 文件作为日记条目：

1
---
2
name: 日记标题
3
date: 2024-01-15
4
tags: ["生活", "感悟"]
5
image: ["photo1.jpg", "photo2.jpg"]
6
---
7

8
日记内容...

3. 书架#

新增书籍#

在 src/content/bangumi/books/ 目录下创建 .md 文件：

1
---
2
title: "书籍名称"
3
category: "book"
4
image: "https://example.com/cover.jpg"
5
score: 9.5
6
status: 2
7
comment: "我的评价"
8
tags: ["科幻", "小说"]
9
published: "2024-01-01"
10
---
11

12
书籍简介...

status 状态值#

1 - 想看（wish）
2 - 看过（collect）
3 - 在看（doing）
4 - 搁置（on_hold）
5 - 抛弃（dropped）

4. 影视与游戏#

新增影视作品#

在 src/content/bangumi/movies/ 目录下创建 .md 文件：

1
---
2
title: "电影名称"
3
category: "real"
4
subcategory: "movie"
5
image: "https://example.com/cover.jpg"
6
score: 9.4
7
status: 2
8
comment: "我的评价"
9
tags: ["科幻", "冒险"]
10
published: "2014-01-01"
11
---
12

13
电影简介...

新增游戏#

在 src/content/bangumi/games/ 目录下创建 .md 文件：

1
---
2
title: "游戏名称"
3
category: "game"
4
image: "https://example.com/cover.jpg"
5
score: 9.8
6
status: 3
7
comment: "我的评价"
8
tags: ["冒险", "开放世界"]
9
published: "2024-05-12"
10
---
11

12
游戏简介...

category 分类值#

book - 书籍
anime - 动漫
game - 游戏
real - 影视

subcategory 子分类（仅影视）#

movie - 电影
tv - 电视剧
anime - 动漫
documentary - 纪录片

5. 更新日志#

新增更新记录#

在 src/content/changelog/ 目录下创建 .md 文件：

1
---
2
version: "v1.0.1"
3
date: 2024-01-15
4
time: "10:30"
5
type: feature
6
description: "新增功能描述"
7
---

type 类型值#

feature - 新功能
improvement - 改进
fix - 修复
removal - 删除

6. 日常规划#

新增规划条目#

在 src/content/routines/ 目录下创建 .md 文件：

1
---
2
name: 晚间学习
3
time: "20:00 - 22:00"
4
description: 学习新技术
5
icon: 📚
6
color: "#6366f1"
7
updatedAt: 2024-01-15
8
---
9

10
## 学习内容
11

12
- 阅读技术文档
13
- 编写代码
14
- 总结笔记

7. 足迹#

新增地点记录#

在 src/content/life/places/ 目录下创建 .md 文件：

1
---
2
province: 北京市
3
city: 朝阳区
4
district: 三里屯
5
visitCount: 5
6
date: 2024-01-10
7
experience: 繁华的商业区，有很多时尚店铺和美食
8
---

8. 音乐播放器#

配置歌单#

修改 src/config/musicConfig.ts 文件：

1
playlists: [
2
  {
3
    id: "daily",
4
    name: "每日推荐",
5
    server: "netease",
6
    type: "playlist",
7
    playlistId: "8659142201"
8
  },
9
  {
10
    id: "classical",
11
    name: "古典音乐",
12
    server: "tencent",
13
    type: "playlist",
14
    playlistId: "5575587639"
15
  },
16
]

展开收起

支持的平台#

netease - 网易云音乐
tencent - QQ音乐
kugou - 酷狗音乐

注意事项#

图片路径：使用外部 URL 或相对于 src/content/ 目录的相对路径
日期格式：使用 YYYY-MM-DD 格式
排序：大多数功能按日期倒序排列，最新的在前面
缓存：修改内容后需要重启开发服务器或重新构建
图标：优先使用项目已有的图标库，避免外部依赖

开发命令#

Terminal window

1
# 启动开发服务器
2
npm run dev
3

4
# 构建生产版本
5
npm run build
6

7
# 预览生产版本
8
npm run preview

🔥 Firefly 更新逻辑设计

Mon, 06 Jul 2026 00:00:00 GMT

本文档详细描述 Firefly 博客系统的三种更新类型（写作内容、前端代码、后端代码）的检测机制、更新策略和实现方法。

📋 核心原则#

1.1 更新分离原则#

将更新分为三个独立维度，各自独立检测、独立更新：

维度	检测范围	更新方式	用户干预
写作内容	`src/content/` 目录	自动检测 + 自动构建	无需干预
前端代码	`src/` 目录（排除 content）	检测提示 + 用户确认后更新	需要确认
后端代码	`admin/` 目录	检测提示 + 用户确认后更新	需要确认

1.2 配置保留原则#

后端更新时，必须保留用户的个性化配置（密码、密钥等），不能被覆盖。

1.3 无冲突原则#

三种更新互不干扰，可独立进行，不会互相覆盖。

🔧 架构设计#

2.1 更新检测机制#

2.1.1 基于 GitHub API 的差异检测#

使用 GitHub REST API 的 /repos/{owner}/{repo}/compare/{base}...{head} 接口，比较本地当前提交与远程主分支的差异。

检测流程：

1
本地当前 commit SHA
2
        ↓
3
   GitHub API
4
        ↓
5
获取差异文件列表
6
        ↓
7
按路径分类（content / frontend / backend）
8
        ↓
9
返回各维度更新状态

2.1.2 差异分类规则#

1
文件路径前缀          → 更新类型
2
───────────────────────────────────
3
src/content/          → 写作内容更新
4
src/                  → 前端代码更新（排除 content）
5
admin/                → 后端代码更新
6
其他路径              → 不处理

注意：单个提交可能同时包含多种更新类型，需分别标记。

2.1.3 检测频率#

场景	检测方式	频率
后台页面加载	主动检测	每次页面刷新
定时检测	定时任务	每 5 分钟
手动触发	用户点击检测按钮	按需

2.2 更新状态模型#

1
interface UpdateStatus {
2
  hasContentUpdate: boolean;      // 是否有写作内容更新
3
  hasFrontendUpdate: boolean;     // 是否有前端代码更新
4
  hasBackendUpdate: boolean;      // 是否有后端代码更新
5
  lastChecked: Date;              // 最后检测时间
6
  latestCommit: string;           // 远程最新 commit SHA
7
  currentCommit: string;          // 本地当前 commit SHA
8
  contentChanges: string[];       // content 变更文件列表
9
  frontendChanges: string[];      // 前端变更文件列表
10
  backendChanges: string[];       // 后端变更文件列表
11
}

📝 写作内容更新#

3.1 更新场景#

用户在本地 Obsidian 写好文章后推送到 GitHub，服务器自动检测并同步。

3.2 检测逻辑#

1
// 检测 content 目录是否有变更
2
const hasContentUpdate = diffFiles.some(file =>
3
  file.startsWith('src/content/')
4
);
5

6
// 获取 content 变更详情
7
const contentChanges = diffFiles.filter(file =>
8
  file.startsWith('src/content/')
9
);

3.3 更新流程#

1
GitHub 推送
2
    ↓
3
Webhook 触发 / 定时检测
4
    ↓
5
检测到 content 目录有更新
6
    ↓
7
自动执行：git pull → pnpm build → 部署前端
8
    ↓
9
用户访问博客即可看到新文章

3.4 关键特性#

✅ 完全自动化：无需用户干预，后台自动完成
✅ 静默更新：更新过程不影响用户访问
✅ 增量构建：仅重新编译变更的内容（Astro 支持增量构建）

3.5 实现方案#

方案 A：GitHub Webhook（推荐）#

当 GitHub 收到 push 时，立即触发服务器更新：

.github/workflows/content-update.yml展开收起

1
name: Content Update
2

3
on:
4
  push:
5
    paths:
6
      - 'src/content/**'
7
    branches: [main]
8

9
jobs:
10
  notify-server:
11
    runs-on: ubuntu-latest
12
    steps:
13
      - name: Notify server
14
        env:
15
          SERVER_URL: ${{ secrets.SERVER_URL }}
16
          API_KEY: ${{ secrets.API_KEY }}
17
        run: |
18
          curl -X POST "$SERVER_URL/api/system/content-update" \
19
            -H "Authorization: Bearer $API_KEY" \
20
            -H "Content-Type: application/json" \
21
            -d '{"type": "content"}'

展开收起

方案 B：定时轮询#

服务器每 5 分钟检测一次 GitHub：

1
// 定时检测任务
2
setInterval(async () => {
3
  const status = await checkUpdateStatus();
4
  if (status.hasContentUpdate) {
5
    await updateContent();
6
  }
7
}, 5 * 60 * 1000);

🎨 前端代码更新#

4.1 更新场景#

主题框架更新（样式、布局、组件、配置结构等）。

4.2 检测逻辑#

1
// 检测前端代码是否有变更（排除 content）
2
const hasFrontendUpdate = diffFiles.some(file =>
3
  file.startsWith('src/') &&
4
  !file.startsWith('src/content/')
5
);
6

7
// 获取前端变更详情
8
const frontendChanges = diffFiles.filter(file =>
9
  file.startsWith('src/') &&
10
  !file.startsWith('src/content/')
11
);

4.3 更新流程#

1
检测到前端代码有更新
2
    ↓
3
后台显示醒目提示："发现前端更新，是否立即更新？"
4
    ↓
5
用户点击"更新"按钮
6
    ↓
7
执行：git pull → pnpm build → 部署前端
8
    ↓
9
更新完成提示

4.4 关键特性#

✅ 用户确认：必须用户手动确认才能更新
✅ 不影响内容：前端更新不涉及 content 目录，不会覆盖用户文章
✅ 版本对比：显示更新内容摘要，让用户了解更新内容

4.5 后台提示设计#

1
┌─────────────────────────────────────────────┐
2
│  ⚠️ 发现前端更新！                           │
3
│                                             │
4
│  更新内容：                                  │
5
│  • 修改了导航栏样式                          │
6
│  • 新增了深色模式支持                        │
7
│  • 修复了移动端布局问题                      │
8
│                                             │
9
│  更新时间：2024-01-01 12:00                 │
10
│                                             │
11
│  [立即更新]  [稍后提醒]                      │
12
└─────────────────────────────────────────────┘

🖥️ 后端代码更新#

5.1 更新场景#

后台管理系统更新（API、功能、安全补丁等）。

5.2 检测逻辑#

1
// 检测 admin 目录是否有变更
2
const hasBackendUpdate = diffFiles.some(file =>
3
  file.startsWith('admin/')
4
);
5

6
// 获取后端变更详情
7
const backendChanges = diffFiles.filter(file =>
8
  file.startsWith('admin/')
9
);

5.3 更新流程#

1
检测到后端代码有更新
2
    ↓
3
后台显示醒目提示："发现后端更新，是否立即更新？"
4
    ↓
5
用户点击"更新"按钮
6
    ↓
7
执行：git stash（保存本地配置）
8
    ↓
9
执行：git pull → 更新依赖 → 构建后端 → PM2 重启
10
    ↓
11
执行：git stash pop（恢复本地配置）
12
    ↓
13
更新完成提示

5.4 配置保留策略#

核心问题：用户修改的 .env 文件（密码、密钥等）不能被 git pull 覆盖。

解决方案：

方案 A：.gitignore（推荐）#

将 .env 文件加入 .gitignore，确保不会被版本控制：

.gitignore

1
.env
2
admin/.env
3
admin/node_modules/
4
admin/dist/

优点：简单可靠，配置文件永远不会被覆盖
缺点：首次部署需要手动创建 .env

方案 B：git stash（备选）#

在 pull 前暂存本地修改，pull 后恢复：

Terminal window

1
# 更新脚本中的配置保留逻辑
2
git stash
3
git pull origin main
4
git stash pop

优点：即使配置文件在 git 中也能保留
缺点：可能产生冲突，需要手动解决

方案 C：配置备份（推荐配合方案 A）#

在更新前备份配置文件：

Terminal window展开收起

1
# 更新脚本中的配置保留逻辑
2
BACKUP_DIR="/www/firefly/backup"
3
mkdir -p $BACKUP_DIR
4

5
# 备份配置文件
6
if [ -f ".env" ]; then
7
  cp .env $BACKUP_DIR/.env.backup
8
fi
9

10
if [ -f "admin/.env" ]; then
11
  cp admin/.env $BACKUP_DIR/admin.env.backup
12
fi
13

14
# 更新代码
15
git pull origin main
16

17
# 恢复配置文件（如果被覆盖）
18
if [ -f $BACKUP_DIR/.env.backup ]; then
19
  cp $BACKUP_DIR/.env.backup .env
20
fi
21

22
if [ -f $BACKUP_DIR/admin.env.backup ]; then
23
  cp $BACKUP_DIR/admin.env.backup admin/.env
24
fi

展开收起

5.5 关键特性#

✅ 用户确认：必须用户手动确认才能更新
✅ 配置保留：用户密码、密钥等配置不会被覆盖
✅ 无缝重启：PM2 优雅重启，不中断服务
✅ 版本对比：显示更新内容摘要

🔄 三种更新的协调机制#

6.1 互斥更新#

确保同一时间只有一种更新在执行：

1
let isUpdating = false;
2

3
async function performUpdate(type: 'content' | 'frontend' | 'backend') {
4
  if (isUpdating) {
5
    throw new Error('正在执行其他更新，请稍后重试');
6
  }
7

8
  try {
9
    isUpdating = true;
10
    // 执行更新逻辑
11
  } finally {
12
    isUpdating = false;
13
  }
14
}

6.2 更新优先级#

优先级	更新类型	说明
1	写作内容	自动执行，优先级最高
2	前端代码	用户确认后执行
3	后端代码	用户确认后执行

6.3 冲突处理#

场景：用户在后台编辑了文章，同时本地也推送了文章更新。

解决方案：

1
后台编辑文章
2
    ↓
3
保存到本地文件
4
    ↓
5
本地推送文章到 GitHub
6
    ↓
7
服务器检测到冲突
8
    ↓
9
提示用户："检测到冲突，请手动解决"
10
    ↓
11
用户选择：保留服务器版本 / 保留 GitHub 版本 / 手动合并

📦 打包与部署策略#

7.1 前端打包#

Terminal window

1
# 完整构建（包含所有内容）
2
pnpm build
3

4
# 构建产物位置
5
dist/
6
├── index.html
7
├── assets/
8
│   ├── js/
9
│   ├── css/
10
│   └── images/
11
├── posts/
12
├── books/
13
├── movies/
14
└── ...

7.2 后端打包#

Terminal window

1
# 构建后端
2
cd admin
3
npm run build
4

5
# 构建产物位置
6
admin/dist/
7
├── app.js
8
├── controllers/
9
├── routes/
10
├── services/
11
└── ...

7.3 部署流程#

1
本地开发完成
2
    ↓
3
git commit + push
4
    ↓
5
服务器检测到更新
6
    ↓
7
根据更新类型执行对应操作：
8
    ├── 内容更新 → 自动构建前端 → 部署到 Nginx
9
    ├── 前端更新 → 用户确认 → 构建前端 → 部署到 Nginx
10
    └── 后端更新 → 用户确认 → 构建后端 → PM2 重启

🔌 API 接口设计#

8.1 检测更新接口#

1
GET /api/system/check-update

响应：

1
{
2
  "code": 200,
3
  "data": {
4
    "hasContentUpdate": true,
5
    "hasFrontendUpdate": false,
6
    "hasBackendUpdate": true,
7
    "lastChecked": "2024-01-01T12:00:00Z",
8
    "latestCommit": "abc123",
9
    "currentCommit": "def456",
10
    "contentChanges": [
11
      "src/content/posts/new-article.md",
12
      "src/content/books/new-book.md"
13
    ],
14
    "frontendChanges": [],
15
    "backendChanges": [
16
      "admin/controllers/postsController.ts",
17
      "admin/routes/config.ts"
18
    ]
19
  }
20
}

展开收起

8.2 更新内容接口#

1
POST /api/system/update-content

响应：

1
{
2
  "code": 200,
3
  "message": "内容更新完成",
4
  "data": {
5
    "updatedFiles": ["src/content/posts/new-article.md"],
6
    "buildTime": "3.5s"
7
  }
8
}

8.3 更新前端接口#

1
POST /api/system/update-frontend

响应：

1
{
2
  "code": 200,
3
  "message": "前端更新完成",
4
  "data": {
5
    "updatedFiles": ["src/components/Navbar.astro"],
6
    "buildTime": "15.2s"
7
  }
8
}

8.4 更新后端接口#

1
POST /api/system/update-backend

响应：

1
{
2
  "code": 200,
3
  "message": "后端更新完成",
4
  "data": {
5
    "updatedFiles": ["admin/controllers/postsController.ts"],
6
    "restartTime": "2.1s"
7
  }
8
}

📊 更新日志#

9.1 记录更新历史#

每次更新都会记录到日志文件：

logs/update-history.json

1
[
2
  {
3
    "id": "1",
4
    "type": "content",
5
    "trigger": "webhook",
6
    "timestamp": "2024-01-01T12:00:00Z",
7
    "commits": ["abc123"],
8
    "updatedFiles": ["src/content/posts/new-article.md"],
9
    "status": "success",
10
    "duration": 3500
11
  }
12
]

9.2 后台展示#

在后台管理面板显示最近更新历史：

1
┌─────────────────────────────────────────────┐
2
│  更新历史                                   │
3
│                                             │
4
│  [内容] 2024-01-01 12:00  自动更新成功       │
5
│    • 新增文章：《我的第一篇博客》             │
6
│                                             │
7
│  [前端] 2024-01-01 10:30  用户确认更新       │
8
│    • 更新导航栏组件                          │
9
│                                             │
10
│  [后端] 2024-01-01 09:00  用户确认更新       │
11
│    • 修复文章加密问题                        │
12
└─────────────────────────────────────────────┘

🔧 实现代码示例#

10.1 更新检测服务#

services/updateService.ts展开收起

1
import axios from 'axios';
2

3
class UpdateService {
4
  private readonly GITHUB_API = 'https://api.github.com';
5
  private readonly REPO_OWNER = 'CuteLeaf';
6
  private readonly REPO_NAME = 'Firefly';
7

8
  async checkUpdate(): Promise<UpdateStatus> {
9
    // 获取本地当前 commit
10
    const currentCommit = await this.getCurrentCommit();
11

12
    try {
13
      // 调用 GitHub API 比较差异
14
      const response = await axios.get(
15
        `${this.GITHUB_API}/repos/${this.REPO_OWNER}/${this.REPO_NAME}/compare/${currentCommit}...main`
16
      );
17

18
      const files = response.data.files?.map((f: { filename: string }) => f.filename) || [];
19

20
      return {
21
        hasContentUpdate: files.some(f => f.startsWith('src/content/')),
22
        hasFrontendUpdate: files.some(f => f.startsWith('src/') && !f.startsWith('src/content/')),
23
        hasBackendUpdate: files.some(f => f.startsWith('admin/')),
24
        lastChecked: new Date(),
25
        latestCommit: response.data.head.sha,
26
        currentCommit,
27
        contentChanges: files.filter(f => f.startsWith('src/content/')),
28
        frontendChanges: files.filter(f => f.startsWith('src/') && !f.startsWith('src/content/')),
29
        backendChanges: files.filter(f => f.startsWith('admin/')),
30
      };
31
    } catch (error) {
32
      return {
33
        hasContentUpdate: false,
34
        hasFrontendUpdate: false,
35
        hasBackendUpdate: false,
36
        lastChecked: new Date(),
37
        latestCommit: currentCommit,
38
        currentCommit,
39
        contentChanges: [],
40
        frontendChanges: [],
41
        backendChanges: [],
42
      };
43
    }
44
  }
45

46
  private async getCurrentCommit(): Promise<string> {
47
    // 通过 git 命令获取当前 commit
48
    const { execSync } = require('child_process');
49
    try {
50
      return execSync('git rev-parse HEAD', { encoding: 'utf-8' }).trim();
51
    } catch {
52
      return 'unknown';
53
    }
54
  }
55
}

展开收起

10.2 更新执行脚本#

1
#!/bin/bash
2
# update.sh - 统一更新脚本
3

4
set -e
5

6
TYPE="$1"
7
BACKUP_DIR="/www/firefly/backup"
8

9
echo "=================================="
10
echo "  Firefly 更新脚本"
11
echo "  类型: $TYPE"
12
echo "=================================="
13

14
# 创建备份目录
15
mkdir -p $BACKUP_DIR
16

17
# 备份配置文件
18
if [ -f ".env" ]; then
19
  cp .env $BACKUP_DIR/.env.backup
20
fi
21
if [ -f "admin/.env" ]; then
22
  cp admin/.env $BACKUP_DIR/admin.env.backup
23
fi
24

25
# 拉取代码
26
echo "[1/3] 拉取最新代码..."
27
git pull origin main
28

29
# 根据类型执行不同操作
30
case $TYPE in
31
  content)
32
    echo "[2/3] 构建前端（仅内容）..."
33
    pnpm build
34
    echo "[3/3] 部署前端..."
35
    cp -r dist/* /www/wwwroot/firefly/
36
    ;;
37

38
  frontend)
39
    echo "[2/3] 构建前端..."
40
    pnpm build
41
    echo "[3/3] 部署前端..."
42
    cp -r dist/* /www/wwwroot/firefly/
43
    ;;
44

45
  backend)
46
    echo "[2/3] 构建后端..."
47
    cd admin
48
    npm install
49
    npm run build
50
    cd ..
51
    echo "[3/3] 重启后台服务..."
52
    pm2 restart firefly-admin
53
    ;;
54
esac
55

56
# 恢复配置文件
57
if [ -f $BACKUP_DIR/.env.backup ]; then
58
  cp $BACKUP_DIR/.env.backup .env
59
fi
60
if [ -f $BACKUP_DIR/admin.env.backup ]; then
61
  cp $BACKUP_DIR/admin.env.backup admin/.env
62
fi
63

64
echo "=================================="
65
echo "  更新完成！"
66
echo "=================================="

展开收起

📋 总结#

更新逻辑对照表#

更新类型	检测方式	更新方式	配置保留	用户干预
写作内容	GitHub API / Webhook	自动构建 + 部署	不涉及	无
前端代码	GitHub API	用户确认后构建 + 部署	不涉及	需要确认
后端代码	GitHub API	用户确认后构建 + 重启	.gitignore + 备份	需要确认

核心设计思想#

内容更新自动化：用户写文章推送到 GitHub，博客自动更新，无需任何操作
代码更新人工化：框架更新需要用户确认，避免意外破坏现有功能
配置保护严格化：用户密码、密钥等配置永远不会被覆盖
更新过程透明化：后台显示更新状态、历史记录和变更详情

实现这个更新系统后，你可以：

在 Obsidian 写文章，推送到 GitHub，博客自动同步
收到前端/后端更新提示时，选择性更新
完全不用担心配置被覆盖

让写作更专注，让更新更安心！🌌

Firefly 一款清新美观的 Astro 博客主题模板

Sat, 04 Jul 2026 00:00:00 GMT

🌟 项目概述#

Firefly 是一款基于 Astro 框架和 Fuwari 模板开发的清新美观且现代化个人博客主题模板，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。

🖥️在线预览： Firefly - Demo site

🏠我的博客： https://blog.cuteleaf.cn

📝Firefly使用文档： https://docs-firefly.cuteleaf.cn

⭐Firefly开源地址：https://github.com/CuteLeaf/Firefly

⭐Fuwari开源地址：https://github.com/saicaca/fuwari

CuteLeaf

Firefly

Waiting for api.github.com...

Waiting for api.github.com...

00K

Waiting...

Firefly

🚀 技术架构#

静态站点生成: 基于 Astro ，提供极快的加载速度和优秀的 SEO 优化
TypeScript 支持: 完整的类型安全，提升开发体验和代码质量
响应式设计: 使用 Tailwind CSS 构建，完美适配桌面端和移动端
组件化开发: 支持 Astro、Svelte 组件，灵活可扩展

📖 配置说明#

📚 详细配置文档: 查看 Firefly使用文档获取完整的配置指南

Firefly 简单使用指南

Fri, 02 Jan 1970 00:00:00 GMT

这个博客模板是基于 Astro 构建的。对于本指南中未提及的内容，您可以在 Astro 文档中找到答案。

文章的 Front-matter#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
description: 这是我新 Astro 博客的第一篇文章。
5
image: ./cover.jpg
6
tags: [前端, 开发]
7
category: 前端开发
8
draft: false
9
---

属性	描述
`title`	文章标题。
`published`	文章发布日期。
`updated`	文章更新日期。如果未设置，将默认使用发布日期。
`pinned`	是否将此文章置顶在文章列表顶部。
`description`	文章的简短描述。显示在首页上。
`image`	文章封面图片路径。 1. 以 `http://` 或 `https://` 开头：使用网络图片 2. 以 `/` 开头：`public` 目录中的图片 3. 不带任何前缀：相对于 markdown 文件的路径
`tags`	文章标签。
`category`	文章分类。
`lang`	文章语言代码（如 `zh-CN`）。仅当文章语言与站点默认语言不同时设置。
`licenseName`	文章内容的许可证名称。
`licenseUrl`	文章内容的许可证链接。
`author`	文章作者。
`sourceLink`	文章内容的来源链接或参考。
`draft`	如果这篇文章仍是草稿，则不会显示。
`comment`	是否启用此文章的评论功能。默认为 `true`。
`slug`	自定义文章 URL 路径。如果不设置，将使用文件名作为 URL。
`password`	文章密码。设置后文章内容将被 AES-256-GCM 加密，访客需输入密码才能查看。
`passwordHint`	密码提示。显示在密码输入框上方，帮助访客回忆密码，也可以不加。

文章文件的放置位置#

您的文章文件应放置在 src/content/posts/ 目录中。您也可以创建子目录来更好地组织您的文章和资源。

1
src/content/posts/
2
├── post-1.md
3
└── post-2/
4
    ├── cover.png
5
    └── index.md

自定义文章 URL (Slug)#

什么是 Slug？#

Slug 是文章 URL 路径的自定义部分。如果不设置 slug，系统将使用文件名作为 URL。

Slug 使用示例#

示例 1：使用文件名作为 URL#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
---

文件：src/content/posts/my-first-blog-post.md

URL：/posts/my-first-blog-post

示例 2：自定义 Slug#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
slug: hello-world
5
---

文件：src/content/posts/my-first-blog-post.md

URL：/posts/hello-world

示例 3：其他语言文件名使用Slug#

1
---
2
title: 如何使用 Firefly 博客主题
3
published: 2023-09-09
4
slug: how-to-use-firefly-blog-theme
5
---

文件：src/content/posts/如何使用Firefly博客主题.md

URL：/posts/how-to-use-firefly-blog-theme

Slug 使用建议#

使用英文和连字符：my-awesome-post 而不是 my awesome post
保持简洁：避免过长的 slug
具有描述性：让 URL 能够反映文章内容
避免特殊字符：只使用字母、数字和连字符
保持一致性：在整个博客中使用相似的命名模式

注意事项#

Slug 一旦设置并发布，建议不要随意更改，以免影响 SEO 和已存在的链接
如果多个文章使用相同的 slug，后面的文章会覆盖前面的
Slug 会自动转换为小写

Firefly 代码块示例

Sat, 03 Jan 1970 00:00:00 GMT

在这里，我们将探索如何使用 Expressive Code 展示代码块。提供的示例基于官方文档，您可以参考以获取更多详细信息。

表达性代码#

语法高亮#

语法高亮

常规语法高亮#

1
console.log('此代码有语法高亮!')

渲染 ANSI 转义序列#

Terminal window展开收起

1
Standard ANSI colors:
2
- Dimmed:      Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
3
- Foreground:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
4
- Background:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
5
- Reversed:    Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
6

7
8-bit colors (showing colors 160-171 as an example):
8
- Dimmed:      160  161  162  163  164  165  166  167  168  169  170  171 
9
- Foreground:  160  161  162  163  164  165  166  167  168  169  170  171 
10
- Background:  160  161  162  163  164  165  166  167  168  169  170  171 
11
- Reversed:    160  161  162  163  164  165  166  167  168  169  170  171 
12

13
24-bit colors (full RGB):
14
- Dimmed:      ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
15
- Foreground:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
16
- Background:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
17
- Reversed:    ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
18

19
Font styles:
20
- Default
21
- Bold
22
- Dimmed
23
- Italic
24
- Underline
25
- Reversed
26
- Strikethrough

展开收起

编辑器和终端框架#

编辑器和终端框架

代码编辑器框架#

my-test-file.js

1
console.log('标题属性示例')

src/content/index.html

1
<div>文件名注释示例</div>

终端框架#

Terminal window

1
echo "此终端框架没有标题"

PowerShell 终端示例

1
Write-Output "这个有标题!"

覆盖框架类型#

1
echo "看，没有框架!"

PowerShell Profile.ps1

1
# 如果不覆盖，这将是一个终端框架
2
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
3
New-Alias tail Watch-Tail

文本和行标记#

文本和行标记

标记整行和行范围#

1
// 第1行 - 通过行号定位
2
// 第2行
3
// 第3行
4
// 第4行 - 通过行号定位
5
// 第5行
6
// 第6行
7
// 第7行 - 通过范围 "7-8" 定位
8
// 第8行 - 通过范围 "7-8" 定位

选择行标记类型 (mark, ins, del)#

line-markers.js

1
function demo() {
2
  console.log('此行标记为已删除')
3
  // 此行和下一行标记为已插入
4
  console.log('这是第二个插入行')
5

6
  return '此行使用中性默认标记类型'
7
}

为行标记添加标签#

labeled-line-markers.jsx

1
<button
2
  role="button"
3
  {...props}
4
  value={value}
5
  className={buttonClassName}
6
  disabled={disabled}
7
  active={active}
8
>
9
  {children &&
10
    !active &&
11
    (typeof children === 'string' ? <span>{children}</span> : children)}
12
</button>

在单独行上添加长标签#

labeled-line-markers.jsx展开收起

1
<button
2
  role="button"
3
  {...props}
4

5
  value={value}
6
  className={buttonClassName}
7

8
  disabled={disabled}
9
  active={active}
10
>
11

12
  {children &&
13
    !active &&
14
    (typeof children === 'string' ? <span>{children}</span> : children)}
15
</button>

展开收起

使用类似 diff 的语法#

1
此行将标记为已插入
2
此行将标记为已删除
3
这是常规行

1
--- a/README.md
2
+++ b/README.md
3
@@ -1,3 +1,4 @@
4
+this is an actual diff file
5
-all contents will remain unmodified
6
 no whitespace will be removed either

结合语法高亮和类似 diff 的语法#

1
function thisIsJavaScript() {
2
  // 整个块都会以 JavaScript 高亮显示，
3
  // 并且我们仍然可以为其添加 diff 标记！
4
  console.log('要删除的旧代码')
5
  console.log('新的闪亮代码！')
6
}

标记行内的单独文本#

1
function demo() {
2
  // 标记行内的任何给定文本
3
  return '支持给定文本的多个匹配项';
4
}

正则表达式#

1
console.log('单词 yes 和 yep 将被标记。')

转义正斜杠#

Terminal window

1
echo "Test" > /home/test.txt

选择内联标记类型 (mark, ins, del)#

1
function demo() {
2
  console.log('这些是插入和删除的标记类型');
3
  // return 语句使用默认标记类型
4
  return true;
5
}

自动换行#

自动换行

为每个块配置自动换行#

1
// 启用换行的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// wrap=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

配置换行的缩进#

1
// preserveIndent 示例（默认启用）
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// preserveIndent=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

可折叠部分#

可折叠部分


5 collapsed lines
1
// 所有这些样板设置代码将被折叠
2
import { someBoilerplateEngine } from '@example/some-boilerplate'
3
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'
4

5
const engine = someBoilerplateEngine(evenMoreBoilerplate())
6

7
// 这部分代码默认可见
8
engine.doSomething(1, 2, 3, calcFn)
9

10
function calcFn() {
11
  // 您可以有多个折叠部分
3 collapsed lines
12
  const a = 1
13
  const b = 2
14
  const c = a + b
15

16
  // 这将保持可见
17
  console.log(`计算结果: ${a} + ${b} = ${c}`)
18
  return c
19
}
20

4 collapsed lines
21
// 直到块末尾的所有代码将再次被折叠
22
engine.closeConnection()
23
engine.freeMemory()
24
engine.shutdown({ reason: '示例样板代码结束' })

展开收起

行号#

行号

为每个块显示行号#

1
// 此代码块将显示行号
2
console.log('来自第2行的问候!')
3
console.log('我在第3行')

// 此块禁用行号
console.log('你好?')
console.log('抱歉，你知道我在第几行吗?')

更改起始行号#

5
console.log('来自第5行的问候!')
6
console.log('我在第6行')

Firefly 布局系统详解

Sat, 03 Jan 1970 00:00:00 GMT

📖 概述#

Firefly 提供了灵活的布局系统，允许您根据内容需求和个人喜好自定义博客的视觉呈现方式。布局系统主要包括侧边栏布局和文章列表布局两个维度，它们相互配合，共同决定了页面的整体结构。

本文将详细介绍 Firefly 的各种布局模式、它们的特点、使用场景，以及不同布局组合的效果。

左侧边栏+列表布局

右侧边栏+网格布局

左侧边栏+三列网格布局

双侧边栏+列表布局

双侧边栏+网格布局

双侧边栏+网格瀑布流布局

一、侧边栏布局系统#

侧边栏是博客页面的重要组成部分，用于展示导航、分类、标签、统计信息等辅助内容。Firefly 支持两种侧边栏布局模式。

1.1 单侧边栏模式#

左侧边栏 (position: “left”)#

左侧边栏布局

右侧边栏 (position: “right”)#

右侧边栏布局

特点#

侧边栏固定在页面其中一侧
文章阅读区域体验更佳，更宽敞
更加简约，没有那么紧凑

适用场景#

传统博客风格
强调导航和分类的博客
需要突出用户资料的个人博客
内容为主，辅助信息次之的场景

Tip

可以通过showBothSidebarsOnPostPage配置是否在文章详情页显示双侧边栏

当position为left或right时开启此项后，文章详情页将显示双侧边栏，主页等其他页面保持单侧边栏

适用在只想用单侧栏，但在文章详情页想用对侧栏的目录等组件的场景

配置示例#

src/config/sidebarConfig.ts

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "left", // 左侧边栏
4
  showBothSidebarsOnPostPage: true, // 是否在文章详情页显示双侧边栏
5
};

1.2 双侧边栏模式 (position: “both”)#

特点#

左右两侧同时存在侧边栏
主内容区域位于中间
最大化利用屏幕空间
可以展示更多辅助信息
适合宽屏显示器

布局结构#

双侧边栏+列表布局

双侧边栏+网格布局

适用场景#

宽屏桌面端浏览
信息密集型博客
需要展示大量辅助内容
专业性强的技术博客

配置示例#

src/config/sidebarConfig.ts

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "both", // 双侧边栏

二、文章列表布局系统#

文章列表是博客首页和归档页的核心内容，Firefly 提供两种展示方式，并支持多种网格配置。

2.1 列表模式 (defaultMode: “list”)#

特点#

单列纵向排列
显示文章封面图
展示更多文章摘要
适合深度阅读

列表布局结构#

列表模式布局

优点#

✅ 视觉冲击力强，封面图吸引眼球
✅ 可以展示更多文章信息（摘要、标签等）
✅ 适合图片内容丰富的博客
✅ 移动端友好，单列更易阅读
✅ 兼容所有侧边栏配置（单侧、双侧）

配置示例#

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "list", // 列表模式
4
    allowSwitch: true,   // 允许用户切换
5
  },
6
};

2.2 网格模式 (defaultMode: “grid”)#

特点#

自适应列数，根据浏览器宽度自动调整
紧凑布局，信息密度高
适合快速浏览

自适应网格#

网格模式通过 columnWidth 配置卡片的最小宽度（单位 px），浏览器会根据容器可用宽度自动计算能容纳多少列。

网格布局

配置示例#

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "grid",
4
    allowSwitch: true,
5
    grid: {
6
      masonry: true,      // 开启瀑布流
7
      columnWidth: 320,   // 卡片最小宽度(px)，浏览器自动计算列数
8
    },
9
  },
10
};

2.3 瀑布流布局 (Masonry)#

Firefly 的网格模式内置了智能瀑布流布局支持，解决了网格布局中因图文混合文章导致的卡片高度不一致导致的空白问题。

瀑布流布局

智能排版：自动将卡片放置到最短的列，最大化利用垂直空间。
消除空白：通过绝对定位精确计算每个卡片的位置，让卡片紧贴上方卡片，消除垂直方向的空白间隙。
自适应列数：瀑布流同样根据 columnWidth 和容器宽度动态计算列数，无需固定配置。
配置灵活：您可以在 siteConfig.ts 中通过 postListLayout.grid.masonry 选项自由开启或关闭此功能。

三、布局组合指南#

Firefly 允许您自由组合侧边栏和文章列表布局。以下是各种组合的效果说明。

侧边栏模式	文章列表模式	推荐度	适用场景
单侧边栏	列表模式	⭐⭐⭐⭐⭐	摄影、设计、生活类博客，强调图片和沉浸感
单侧边栏	网格模式	⭐⭐⭐⭐⭐	技术、笔记类博客，平衡阅读与检索效率
双侧边栏	列表模式	⭐⭐⭐⭐⭐	需要展示大量侧边栏信息的站点
双侧边栏	网格模式	⭐⭐⭐⭐⭐	极客风格，追求最高信息密度

四、响应式布局行为#

Firefly 的布局系统具有智能的响应式设计，会根据屏幕尺寸自动调整。

为了保证最佳阅读体验，系统会在屏幕变窄时自动调整布局：

网格列数自动减少：网格模式的列数由 columnWidth 和容器宽度自动决定，屏幕越窄列数越少。
列表模式 -> 网格模式：当屏幕宽度小于 380px（超小屏设备）时，列表模式会自动切换为网格模式，以保证卡片内容的可读性。
双侧边栏 -> 单侧边栏：当屏幕宽度小于 1280px 时，会根据tabletSidebar配置显示单侧边栏，隐藏其中一个侧边栏，文章目录导航会切换成浮动目录导航。

五、常见问题#

Q1: 如何调整网格列数？#

A: 通过 columnWidth 配置卡片最小宽度即可。值越小，同等宽度下列数越多；值越大，列数越少。浏览器会自动根据可用宽度计算最佳列数。

六、总结#

Firefly 的布局系统给予了您更大的自由度，您都可以通过简单的配置实现。

我们建议您根据自己的内容类型和目标读者的设备偏好，尝试不同的组合，找到最适合您的博客形态。

Firefly 文章加密

Fri, 02 Jan 1970 00:00:00 GMT

这是一篇密码保护的示例文章，用于演示文章加密功能。

MDX 格式文章示例

Fri, 02 Jan 1970 00:00:00 GMT

Tip

Firefly 支持 MDX 和 Markdown 两种类型的文章，你可以在文章中混合使用两种格式，如果没有特别复杂内容和需求，推荐使用 Markdown 格式就够了。

Markdown 和 MDX 的区别#

Markdown (MD) 是一种轻量级标记语言，允许用户使用纯文本格式编写文档，然后将其转换为格式化的HTML。它因其简洁易用的语法而广受欢迎，特别适合编写文档和博客文章。
MDX 是一种扩展了 Markdown 语法的格式，允许在 Markdown 文档中无缝地插入 JSX 代码。通过 MDX，用户可以在文档中嵌入 React 组件，从而实现更丰富的交互性和动态性。

特性	Markdown	MDX
基础语法	支持 (CommonMark)	支持 (CommonMark)
HTML 标签	支持	支持 (作为 JSX)
组件导入	不支持	支持 (import)
动态数据	不支持	支持 (JS 表达式)
样式定制	有限 (class/style)	灵活 (className/CSS-in-JS)

使用组件#

这是一个图标组件：

1
import { Icon } from 'astro-icon/components'
2

3
<div class="flex items-center gap-2 my-4">
4
  <Icon name="fa7-solid:rocket" class="text-4xl text-red-500" />
5
  <span>火箭发射！</span>
6
</div>

火箭发射！

使用 JSX#

你也可以直接写 HTML/JSX：

1
<div className="p-4 bg-blue-100 dark:bg-blue-900 rounded-lg my-4">
2
  这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。
3
</div>

这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。

简单的变量导出#

1
export const year = new Date().getFullYear()
2

3
今年是 {year} 年。

今年是 2026 年。

更多信息，请查看 MDX 文档

MDX 格式文章示例

Fri, 02 Jan 1970 00:00:00 GMT

import { Icon } from ‘astro-icon/components’

Tip

Firefly 支持 MDX 和 Markdown 两种类型的文章，你可以在文章中混合使用两种格式，如果没有特别复杂内容和需求，推荐使用 Markdown 格式就够了。

Markdown 和 MDX 的区别#

Markdown (MD) 是一种轻量级标记语言，允许用户使用纯文本格式编写文档，然后将其转换为格式化的HTML。它因其简洁易用的语法而广受欢迎，特别适合编写文档和博客文章。
MDX 是一种扩展了 Markdown 语法的格式，允许在 Markdown 文档中无缝地插入 JSX 代码。通过 MDX，用户可以在文档中嵌入 React 组件，从而实现更丰富的交互性和动态性。

特性	Markdown	MDX
基础语法	支持 (CommonMark)	支持 (CommonMark)
HTML 标签	支持	支持 (作为 JSX)
组件导入	不支持	支持 (import)
动态数据	不支持	支持 (JS 表达式)
样式定制	有限 (class/style)	灵活 (className/CSS-in-JS)

使用组件#

这是一个图标组件：

你可以在 MDX 文件中导入并使用任何 Astro 组件。

JSX 表达式#

你可以在 MDX 中使用 JavaScript 表达式：

1
{new Date().toLocaleDateString('zh-CN')}

显示结果：{new Date().toLocaleDateString(‘zh-CN’)}

注意事项#

MDX 文件需要使用 .mdx 扩展名
导入语句必须放在文件顶部，frontmatter 之后
组件名称必须大写开头
不要在 MDX 中使用 --- 分隔符，它会被解析为 frontmatter

Markdown 扩展功能

Thu, 01 Jan 1970 00:00:00 GMT

GitHub 仓库卡片#

您可以添加链接到 GitHub 仓库的动态卡片，在页面加载时，仓库信息会从 GitHub API 获取。

CuteLeaf

Firefly

Waiting for api.github.com...

00K

Waiting...

使用代码 ::github{repo="CuteLeaf/Firefly"} 创建 GitHub 仓库卡片。

1
::github{repo="CuteLeaf/Firefly"}

提醒框(Admonitions)配置#

Firefly 采用了 rehype-callouts 插件，支持了四种风格的提醒框主题：GitHub、Obsidian、VitePress 和 Docusaurus。您可以在 src/config/siteConfig.ts 中进行配置：

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  // ...
3
  rehypeCallouts: {
4
    // 选项: "github" | "obsidian" | "vitepress" | "docusaurus"
5
    theme: "github",
6
  },
7
  // ...
8
};

注意：更改配置后需要重启开发服务器才能生效。

以下是各个主题支持的类型列表，每个主题风格和语法不同，可根据喜好选择。

1. GitHub 主题风格#

这是 GitHub 官方支持的 5 种基本类型。

GitHub

基本语法

1
> [!NOTE] NOTE
2
> 突出显示用户应该考虑的信息。
3

4
> [!TIP] TIP
5
> 可选信息，帮助用户更成功。
6

7
> [!IMPORTANT] IMPORTANT
8
> 用户成功所必需的关键信息。
9

10
> [!WARNING] WARNING
11
> 关键内容，需要立即注意。
12

13
> [!CAUTION] CAUTION
14
> 行动的负面潜在后果。
15

16
> [!NOTE] 自定义标题
17
> 这是一个带有自定义标题的示例。

展开收起

2. Obsidian 主题风格#

Obsidian 风格支持非常丰富的类型和别名。

点击展开 Obsidian 语法列表

1
> [!NOTE] NOTE
2
> 通用的笔记块。
3

4
> [!ABSTRACT] ABSTRACT
5
> 文章的摘要。
6

7
> [!SUMMARY] SUMMARY
8
> 文章的总结（同 Abstract）。
9

10
> [!TLDR] TLDR
11
> 太长不看（同 Abstract）。
12

13
> [!INFO] INFO
14
> 提供额外信息。
15

16
> [!TODO] TODO
17
> 需要完成的事项。
18

19
> [!TIP] TIP
20
> 实用技巧或提示。
21

22
> [!HINT] HINT
23
> 暗示（同 Tip）。
24

25
> [!IMPORTANT] IMPORTANT
26
> 重要信息（Obsidian 风格通常使用类似的图标）。
27

28
> [!SUCCESS] SUCCESS
29
> 操作成功。
30

31
> [!CHECK] CHECK
32
> 检查通过（同 Success）。
33

34
> [!DONE] DONE
35
> 已完成（同 Success）。
36

37
> [!QUESTION] QUESTION
38
> 提出问题。
39

40
> [!HELP] HELP
41
> 寻求帮助（同 Question）。
42

43
> [!FAQ] FAQ
44
> 常见问题（同 Question）。
45

46
> [!WARNING] WARNING
47
> 警告信息。
48

49
> [!CAUTION] CAUTION
50
> 注意事项（同 Warning）。
51

52
> [!ATTENTION] ATTENTION
53
> 引起注意（同 Warning）。
54

55
> [!FAILURE] FAILURE
56
> 操作失败。
57

58
> [!FAIL] FAIL
59
> 失败（同 Failure）。
60

61
> [!MISSING] MISSING
62
> 缺失内容（同 Failure）。
63

64
> [!DANGER] DANGER
65
> 危险操作警告。
66

67
> [!ERROR] ERROR
68
> 错误信息（同 Danger）。
69

70
> [!BUG] BUG
71
> 报告软件缺陷。
72

73
> [!EXAMPLE] EXAMPLE
74
> 展示一个例子。
75

76
> [!QUOTE] QUOTE
77
> 引用一段话。
78

79
> [!CITE] CITE
80
> 引证（同 Quote）。
81

82
> [!NOTE] 自定义标题
83
> 这是一个带有自定义标题的示例。

展开收起

Obsidian

3. VitePress 主题风格#

VitePress 风格提供了一套现代化的、扁平的默认样式。目前仅包含与 GitHub 一致的 5 种 基础类型。

点击展开 VitePress 语法列表

1
> [!NOTE] NOTE
2
> 对应 GitHub 的 Note。
3

4
> [!TIP] TIP
5
> 对应 GitHub 的 Tip。
6

7
> [!IMPORTANT] IMPORTANT
8
> 对应 GitHub 的 Important。
9

10
> [!WARNING] WARNING
11
> 对应 GitHub 的 Warning。
12

13
> [!CAUTION] CAUTION
14
> 对应 GitHub 的 Caution。
15

16
> [!TIP] 自定义标题
17
> VitePress 风格同样支持自定义标题。

展开收起

VitePress

4. Docusaurus 主题风格#

Docusaurus 风格提供了一套现代化的提醒框样式，支持 5 种类型。

点击展开 Docusaurus 语法列表

支持以下类型的提醒框：note tip info warning danger

1
:::note
2
突出显示用户应该考虑的信息，即使在快速浏览时也是如此。
3
:::
4

5
:::tip
6
可选信息，帮助用户更成功。
7
:::
8

9
:::info
10
一般信息。
11
:::
12

13
:::warning
14
由于潜在风险需要用户立即注意的关键内容。
15
:::
16

17
:::danger
18
行动的负面潜在后果。
19
:::
20

21
:::tip[自定义标题]
22
可选信息，帮助用户更成功。
23
:::

展开收起

Docusaurus

剧透#

您可以为文本添加剧透。文本也支持 Markdown 语法。

内容被隐藏了哈哈！

1
内容 :spoiler[被隐藏了 **哈哈**]！

图片画廊网格 (Image Grid)#

您可以使用 [grid] 和 [/grid] 标签将多张图片纵向并排展示。这对于展示照片画廊或对比图非常有用。系统会自动根据包裹在其中的图片数量（最多支持并排展示4张）以响应式网格进行布局。

自动补齐图片高度： 同一排中如果有高度、大小或者比例不一的图片，会像「九宫格画廊相册」一样自动撑满。较短或不协调的图片会自动使用 object-cover 进行完美中心裁剪补充视野。图片边框水平彻底对齐无缝隙，但被裁剪后，只有点击图片通过灯箱才能查看完整图片，所以建议尽量避免使用长宽比例不一致的图片在同一排中。

图注恒定底端对齐： 不论上面的图片长宽如何变化，在同一行的所有图像解释文字（图注）都会对标到一条完美的水平基线上了。

示例图片一

示例图片二

基本语法

1
[grid]
2
![示例图片一](./images/firefly1.avif)
3
![示例图片二](./images/firefly2.avif)
4
![示例图片二](./images/firefly3.avif)
5
[/grid]

Markdown Mermaid 图表

Thu, 01 Jan 1970 00:00:00 GMT

GitHub 仓库卡片#

您可以添加链接到 GitHub 仓库的动态卡片，在页面加载时，仓库信息会从 GitHub API 获取。

CuteLeaf

Firefly

Waiting for api.github.com...

00K

Waiting...

使用代码 ::github{repo="CuteLeaf/Firefly"} 创建 GitHub 仓库卡片。

1
::github{repo="CuteLeaf/Firefly"}

提醒框(Admonitions)配置#

Firefly 采用了 rehype-callouts 插件，支持了四种风格的提醒框主题：GitHub、Obsidian、VitePress 和 Docusaurus。您可以在 src/config/siteConfig.ts 中进行配置：

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  // ...
3
  rehypeCallouts: {
4
    // 选项: "github" | "obsidian" | "vitepress" | "docusaurus"
5
    theme: "github",
6
  },
7
  // ...
8
};

注意：更改配置后需要重启开发服务器才能生效。

以下是各个主题支持的类型列表，每个主题风格和语法不同，可根据喜好选择。

1. GitHub 主题风格#

这是 GitHub 官方支持的 5 种基本类型。

GitHub

基本语法

1
> [!NOTE] NOTE
2
> 突出显示用户应该考虑的信息。
3

4
> [!TIP] TIP
5
> 可选信息，帮助用户更成功。
6

7
> [!IMPORTANT] IMPORTANT
8
> 用户成功所必需的关键信息。
9

10
> [!WARNING] WARNING
11
> 关键内容，需要立即注意。
12

13
> [!CAUTION] CAUTION
14
> 行动的负面潜在后果。
15

16
> [!NOTE] 自定义标题
17
> 这是一个带有自定义标题的示例。

展开收起

2. Obsidian 主题风格#

Obsidian 风格支持非常丰富的类型和别名。

点击展开 Obsidian 语法列表

1
> [!NOTE] NOTE
2
> 通用的笔记块。
3

4
> [!ABSTRACT] ABSTRACT
5
> 文章的摘要。
6

7
> [!SUMMARY] SUMMARY
8
> 文章的总结（同 Abstract）。
9

10
> [!TLDR] TLDR
11
> 太长不看（同 Abstract）。
12

13
> [!INFO] INFO
14
> 提供额外信息。
15

16
> [!TODO] TODO
17
> 需要完成的事项。
18

19
> [!TIP] TIP
20
> 实用技巧或提示。
21

22
> [!HINT] HINT
23
> 暗示（同 Tip）。
24

25
> [!IMPORTANT] IMPORTANT
26
> 重要信息（Obsidian 风格通常使用类似的图标）。
27

28
> [!SUCCESS] SUCCESS
29
> 操作成功。
30

31
> [!CHECK] CHECK
32
> 检查通过（同 Success）。
33

34
> [!DONE] DONE
35
> 已完成（同 Success）。
36

37
> [!QUESTION] QUESTION
38
> 提出问题。
39

40
> [!HELP] HELP
41
> 寻求帮助（同 Question）。
42

43
> [!FAQ] FAQ
44
> 常见问题（同 Question）。
45

46
> [!WARNING] WARNING
47
> 警告信息。
48

49
> [!CAUTION] CAUTION
50
> 注意事项（同 Warning）。
51

52
> [!ATTENTION] ATTENTION
53
> 引起注意（同 Warning）。
54

55
> [!FAILURE] FAILURE
56
> 操作失败。
57

58
> [!FAIL] FAIL
59
> 失败（同 Failure）。
60

61
> [!MISSING] MISSING
62
> 缺失内容（同 Failure）。
63

64
> [!DANGER] DANGER
65
> 危险操作警告。
66

67
> [!ERROR] ERROR
68
> 错误信息（同 Danger）。
69

70
> [!BUG] BUG
71
> 报告软件缺陷。
72

73
> [!EXAMPLE] EXAMPLE
74
> 展示一个例子。
75

76
> [!QUOTE] QUOTE
77
> 引用一段话。
78

79
> [!CITE] CITE
80
> 引证（同 Quote）。
81

82
> [!NOTE] 自定义标题
83
> 这是一个带有自定义标题的示例。

展开收起

Obsidian

3. VitePress 主题风格#

VitePress 风格提供了一套现代化的、扁平的默认样式。目前仅包含与 GitHub 一致的 5 种 基础类型。

点击展开 VitePress 语法列表

1
> [!NOTE] NOTE
2
> 对应 GitHub 的 Note。
3

4
> [!TIP] TIP
5
> 对应 GitHub 的 Tip。
6

7
> [!IMPORTANT] IMPORTANT
8
> 对应 GitHub 的 Important。
9

10
> [!WARNING] WARNING
11
> 对应 GitHub 的 Warning。
12

13
> [!CAUTION] CAUTION
14
> 对应 GitHub 的 Caution。
15

16
> [!TIP] 自定义标题
17
> VitePress 风格同样支持自定义标题。

展开收起

VitePress

4. Docusaurus 主题风格#

Docusaurus 风格提供了一套现代化的提醒框样式，支持 5 种类型。

点击展开 Docusaurus 语法列表

支持以下类型的提醒框：note tip info warning danger

1
:::note
2
突出显示用户应该考虑的信息，即使在快速浏览时也是如此。
3
:::
4

5
:::tip
6
可选信息，帮助用户更成功。
7
:::
8

9
:::info
10
一般信息。
11
:::
12

13
:::warning
14
由于潜在风险需要用户立即注意的关键内容。
15
:::
16

17
:::danger
18
行动的负面潜在后果。
19
:::
20

21
:::tip[自定义标题]
22
可选信息，帮助用户更成功。
23
:::

展开收起

Docusaurus

剧透#

您可以为文本添加剧透。文本也支持 Markdown 语法。

内容被隐藏了哈哈！

1
内容 :spoiler[被隐藏了 **哈哈**]！

图片画廊网格 (Image Grid)#

图注恒定底端对齐： 不论上面的图片长宽如何变化，在同一行的所有图像解释文字（图注）都会对标到一条完美的水平基线上了。

示例图片一

示例图片二

基本语法

1
[grid]
2
![示例图片一](./images/firefly1.avif)
3
![示例图片二](./images/firefly2.avif)
4
![示例图片二](./images/firefly3.avif)
5
[/grid]

Markdown PlantUML 图表

Thu, 01 Jan 1970 00:00:00 GMT

Markdown 中 PlantUML 图表指南#

PlantUML 是一种使用纯文本描述图表的工具。你只需要写一段结构化语法，就可以生成时序图、类图、用例图、活动图等常见工程图。

流程图示例#

流程图非常适合表示流程或算法步骤。

graph TD A[开始] --> B{条件检查} B -->|是| C[处理步骤 1] B -->|否| D[处理步骤 2] C --> E[子过程] D --> E subgraph E [子过程详情] E1[子步骤 1] --> E2[子步骤 2] E2 --> E3[子步骤 3] end E --> F{另一个决策} F -->|选项 1| G[结果 1] F -->|选项 2| H[结果 2] F -->|选项 3| I[结果 3] G --> J[结束] H --> J I --> J

时序图示例#

时序图显示对象之间随时间的交互。

sequenceDiagram participant User as 用户 participant WebApp as 网页应用 participant Server as 服务器 participant Database as 数据库 User->>WebApp: 提交登录请求 WebApp->>Server: 发送认证请求 Server->>Database: 查询用户凭据 Database-->>Server: 返回用户数据 Server-->>WebApp: 返回认证结果 alt 认证成功 WebApp->>User: 显示欢迎页面 WebApp->>Server: 请求用户数据 Server->>Database: 获取用户偏好 Database-->>Server: 返回偏好设置 Server-->>WebApp: 返回用户数据 WebApp->>User: 加载个性化界面 else 认证失败 WebApp->>User: 显示错误消息 WebApp->>User: 提示重新输入 end

甘特图示例#

甘特图非常适合显示项目进度和时间线。

gantt title 网站开发项目时间线 dateFormat YYYY-MM-DD axisFormat %m/%d section 设计阶段需求分析 :a1, 2023-10-01, 7d UI设计 :a2, after a1, 10d 原型创建 :a3, after a2, 5d section 开发阶段前端开发 :b1, 2023-10-20, 15d 后端开发 :b2, after a2, 18d 数据库设计 :b3, after a1, 12d section 测试阶段单元测试 :c1, after b1, 8d 集成测试 :c2, after b2, 10d 用户验收测试 :c3, after c2, 7d section 部署生产环境部署 :d1, after c3, 3d 发布 :milestone, after d1, 0d

类图示例#

类图显示系统的静态结构，包括类、属性、方法及其关系。

classDiagram class User { +String username +String password +String email +Boolean active +login() +logout() +updateProfile() } class Article { +String title +String content +Date publishDate +Boolean published +publish() +edit() +delete() } class Comment { +String content +Date commentDate +addComment() +deleteComment() } class Category { +String name +String description +addArticle() +removeArticle() } User "1" -- "*" Article : 写作 User "1" -- "*" Comment : 发表 Article "1" -- "*" Comment : 拥有 Article "1" -- "*" Category : 属于

状态图示例#

状态图显示对象在其生命周期中经历的状态序列。

stateDiagram-v2 [*] --> 草稿草稿 --> 审核中 : 提交审核中 --> 草稿 : 拒绝审核中 --> 已批准 : 批准已批准 --> 已发布 : 发布已发布 --> 已归档 : 归档已发布 --> 草稿 : 撤回 state 已发布 { [*] --> 活跃活跃 --> 隐藏 : 临时隐藏隐藏 --> 活跃 : 恢复活跃 --> [*] 隐藏 --> [*] } 已归档 --> [*]

饼图示例#

饼图非常适合显示比例和百分比数据。

pie title 网站流量来源分析 "搜索引擎" : 45.6 "直接访问" : 30.1 "社交媒体" : 15.3 "推荐链接" : 6.4 "其他来源" : 2.6

总结#

Mermaid 是在 Markdown 文档中创建各种类型图表的强大工具。本文演示了如何使用流程图、时序图、甘特图、类图、状态图和饼图。这些图表可以帮助您更清晰地表达复杂的概念、流程和数据结构。

要使用 Mermaid，只需在代码块中指定 mermaid 语言，并使用简洁的文本语法描述图表。Mermaid 会自动将这些描述转换为美观的可视化图表。

尝试在您的下一篇技术博客文章或项目文档中使用 Mermaid 图表 - 它们将使您的内容更加专业且更易理解！

Markdown 使用教程

Thu, 01 Jan 1970 00:00:00 GMT

Markdown 中 Mermaid 图表完整指南#

本文演示如何在 Markdown 文档中使用 Mermaid 创建各种复杂图表，包括流程图、时序图、甘特图、类图和状态图。

流程图示例#

流程图非常适合表示流程或算法步骤。

flowchart TD A[开始] --> B{条件判断} B -->|是| C[执行操作A] B -->|否| D[执行操作B] C --> E[结束] D --> E

时序图示例#

时序图用于展示对象之间的交互顺序。

sequenceDiagram participant 用户 participant 系统 participant 数据库用户->>系统: 请求登录系统->>数据库: 查询用户信息数据库-->>系统: 返回用户数据系统->>系统: 验证密码系统-->>用户: 登录成功

甘特图示例#

甘特图用于项目进度管理。

gantt title 项目开发计划 dateFormat YYYY-MM-DD section 设计需求分析 :done, des1, 2024-01-01, 3d 架构设计 :done, des2, 2024-01-04, 5d section 开发前端开发 :active, dev1, 2024-01-09, 10d 后端开发 : dev2, 2024-01-09, 10d section 测试单元测试 : test1, 2024-01-19, 5d 集成测试 : test2, 2024-01-24, 5d

类图示例#

类图用于展示类之间的关系。

classDiagram class 用户 { -姓名: string -邮箱: string +登录() +退出() } class 文章 { -标题: string -内容: string +发布() +编辑() } 用户 "1" --> "*" 文章 : 发布

状态图示例#

状态图用于展示对象的状态变化。

stateDiagram-v2 [*] --> 草稿草稿 --> 审核中 : 提交审核中 --> 已发布 : 通过审核中 --> 草稿 : 退回已发布 --> [*]

使用方法#

在 Firefly 博客中，您只需在 Markdown 代码块中使用 mermaid 语言标识，即可渲染 Mermaid 图表：

1
```mermaid
2
flowchart TD
3
    A[开始] --> B[结束]

1
Firefly 会自动处理 Mermaid 图表的渲染，支持亮暗主题切换，并提供图表的缩放和拖拽功能。