建站记录：基于 Firefly 的定制改动与写作指南

之前的博客基于 NotionNext 搭建，访问体验上较为卡顿，因此决定基于 Astro 重新整个博客。

本博客基于 Astro 和 Firefly 搭建。这篇文章记录了对上游模板做的主要改动，顺便也整理一下写文章时常用的配置说明。

第一部分：定制改动记录#

1. 侧边栏文件夹树#

上游 Firefly 的文章归类依赖 frontmatter 里的 category 字段，是一个扁平的虚拟分类。我加了一套基于物理目录结构的文件夹树组件，让 src/content/posts/ 下的子文件夹直接映射为可浏览的树形导航。

具体改了这些东西：

src/utils/content-utils.ts：新增 getFolderFromEntryId() 从文章 ID 中提取所在目录路径，getFolderTree() 遍历所有文章构建 FolderTreeNode 树，每个节点带有 directCount（当前目录文章数）和 totalCount（含子目录的总数）。
src/components/widget/FolderTree.astro：新的侧边栏组件，把上面的树渲染成可折叠的目录列表。点击文件夹会跳转到 /archive/?folder=<路径> 来筛选该目录下的文章。当文件夹数超过配置的 collapseThreshold（默认 15）时自动收起。
src/components/controls/ArchivePanel.svelte：归档页面新增了对 ?folder= 参数的支持，并加了时间轴/文件夹两种视图模式的切换。文件夹视图下会在客户端重新按目录组织文章列表。
src/types/config.ts：在 WidgetComponentType 里注册了 folderTree 类型。
src/utils/url-utils.ts：新增 getFolderUrl() 用于生成文件夹筛选链接。

配置上，在 sidebarConfig.ts 的左侧栏添了这个组件，位置设为 sticky。

2. 导航栏精简与滚动隐藏#

原版导航栏有多级下拉菜单（“我的”、“关于”、“链接”等），里面嵌套了相册、番组、GitHub、QQ 群之类的子链接。我把这些全砍了，只保留首页、归档、留言板和关于页的平铺链接。

同时改了几个布局参数：

widthFull: true — 导航栏撑满整个屏幕宽度
menuAlign: "left" — 菜单项左对齐
stickyNavbar: false — 关掉了默认的始终置顶

关掉置顶后，在纯色背景模式（没有 banner 图）下导航栏就会随页面滚走。为了还能方便地回到顶部，在 Layout.astro 里加了一段滚动检测逻辑：

向下滚动超过 80px 后，给导航栏加上 .fixed-navbar（position: fixed，吸顶）和 navbar-hidden（向上偏移隐藏）
往回滚动时移除 navbar-hidden，导航栏浮出

通过比较当前 scrollTop 和上一次的 lastScrollTop 来判断滚动方向，实现效果类似 Headroom.js，但没有引入额外依赖。

3. 全局排版调整#

pageWidth 从 100 调到 120（对应约 1920px），内容区更宽
MainGridLayout.astro 里去掉了 xl:w-[92vw] 的视口限制，改用 px-4 md:px-6 做内边距，整体更贴边
侧边栏的公告和音乐播放器组件关掉了（enable: false），减少视觉噪音

4. 个人信息栏改版#

Profile.astro 里把原来的方形头像改成了圆形（rounded-full，w-32 h-32），去掉了名字下面的彩色分隔线，调大了名字和签名的字号。整体看起来更简洁一些。

5. Twikoo 评论样式修复#

twikoo.css 里有两处 Tailwind CSS v3 的写法在 v4 下不生效：

评论框的 focus:ring-opacity-20 改成了 focus:ring-[var(--primary)]/20
评论左侧边框的 border-opacity-30 改成了 border-l-[var(--btn-regular-bg)]/30

另外在文件顶部加了 @import "tailwindcss" reference，让 CSS 文件内的 @apply 能正确解析 Tailwind 类名。

6. 封面图配置扩展#

在 CoverImageConfig 类型定义里扩展了两组字段：

loading：可以自定义加载时的背景色和过渡动画图片
watermark：预留了水印的位置、透明度、字号、颜色等参数

目前这些只是类型定义，还没有对应的渲染实现，后续需要时再接上。

7. 站点个性化#

这部分不涉及功能改动，就是把上游的示例内容替换成自己的：

站点标题、URL、主题色（hue 205，默认暗色模式）
头像、昵称、签名、社交链接
删掉了所有示例文章和演示图片
关掉了友链和赞助页面

第二部分：文章写作指南#

Front-matter 配置#

每篇文章顶部用 --- 包裹的区域可以配置以下属性：

1
---
2
title: 我的第一篇博客文章
3
published: 2026-04-05
4
description: 文章摘要，会显示在首页卡片上。
5
image: ./cover.jpg
6
tags: [随笔, 技术]
7
category: 技术记录
8
draft: false
9
---

属性	说明
`title`	文章标题
`published`	发布日期
`updated`	更新日期，不填则使用发布日期
`pinned`	设为 `true` 会置顶到首页列表顶部
`description`	摘要，显示在首页卡片上
`image`	封面图路径。`./` 开头表示相对路径，`/` 开头表示 public 目录，也可以用完整 URL
`tags`	标签列表
`category`	分类
`draft`	设为 `true` 则线上不可见，仅本地预览
`password`	设置后文章会被 AES 加密，访客需输入密码才能阅读
`passwordHint`	密码提示，显示在输入框上方
`slug`	自定义 URL 路径，见下文
`lang`	文章语言代码，仅在与站点默认语言不同时需要设置
`comment`	是否启用评论，默认 `true`

文件放置#

文章放在 src/content/posts/ 下。推荐用文件夹把文章和配图打包在一起：

1
src/content/posts/
2
├── 随便写写.md              ← 不带配图的简单文章
3
└── guide/                  ← 用文件夹包起来
4
    ├── cover.avif          ← 封面图
5
    └── index.md            ← 文章正文

这样迁移或删除文章时不会落下散落的图片。文件夹的目录结构同时也会反映在侧边栏的文件夹树里。

自定义 URL (Slug)#

不设 slug 时，URL 就是文件名。设了 slug 可以得到更干净的地址：

1
---
2
title: 如何定制博客
3
slug: how-to-customize
4
---

文件叫 定制教程.md 也没关系，URL 会是 /posts/how-to-customize。

建议：

用英文小写加连字符 -
保持简短且有描述性
发布后尽量别改，否则旧链接会失效