CitrusGrid 二次开发文档总览

本目录下的文档由源码逐文件核对生成。

一、文档地图

二、60 秒认识这个项目

CitrusGrid 是一个纯静态的 Astro 博客主题：

Markdown 文章 (src/content/posts/*.md)
        │
        ├─ astro build ──► dist/*.html（构建期全量预渲染，客户端几乎零 JS）
        │                        │
        │                        └─ scripts/postbuild.js ──► 内联脚本压缩 + modulepreload 注入 + pagefind 索引
        │
        └─ Vite 插件（buildStart）──► .generated/*.json（slug、LQIP 取色、updated 时间）

三个关键设计取向，改之前务必知道：

1. 构建期做完一切能做的事：
   代码高亮（Prism）、图片 LQIP 主色渐变、目录（TOC）数据、SEO JSON-LD、RSS 全都在构建期产出，客户端只负责交互。

2. 样式靠 CSS 变量中转：
   全部颜色 / 阴影 / 圆角收敛到 --wp-* 变量，再由 @theme inline 映射成 Tailwind 的工具类（如 bg-surface）。换肤 = 只改 src/styles/main.css 里的变量值，不用动组件。

3. 插件靠「同名文件 + 契约」接入：
   site.config.ts 里写一个字符串（如 commentScript: 'utterances'），运行时会动态 import src/comments/utterances.ts。加评论系统 = 新增一个文件，不改框架代码。

三、二次开发常见任务索引

四、改动前的三条硬规则

规则一：不要手改 dist/ 和 .generated/

dist/ 是构建产物，.generated/（post-index.json、lqips.json、post-updated.json）由构建脚本自动写入，二者都在 .gitignore 里。要改行为请改生成它们的源码。

规则二：样式改动优先落在 CSS 变量，而不是组件内的 class

组件里大量使用 bg-surface、text-ink-2、border-line 这类由变量桥接出来的语义类（见 main.css 的 @theme inline）。直接改某个组件的颜色会造成暗色模式失效或全站不一致。

规则三：Astro 组件的 <script> 在 Swup 换页时不会重新执行

项目用 Swup 做无刷新导航，只有 #swup-container 内的 DOM 会被替换。所以：

• 页面级脚本必须用 onPageLoad()（src/lib/pageLifecycle.ts）包一层，而不是裸 DOMContentLoaded；
• 常驻 UI（头部、页脚、右下按钮组、音乐播放器）都被刻意放在 #swup-container 之外（见 BaseLayout.astro），保证切页时不重建、不中断播放。

五、验证改动是否生效

pnpm check            # Astro 组件 + 类型检查
pnpm type-check   # tsc --noEmit（覆盖 src 与 scripts）
pnpm format:all     # Biome 检查并修复
pnpm build            # 完整构建（含 postbuild + pagefind）
pnpm preview       # 预览 dist 产物

注意：搜索功能只在 pnpm build 之后可用（pagefind 索引在 postbuild.js 中生成），pnpm dev 下搜索框会提示「搜索索引不可用」。