Shirone 改造记（六）：这个站由哪些零件拼起来

第一篇里说过双仓分离是为什么。这篇说它长什么样。

我把两份目录树完整列一遍，每个文件夹、每个顶层文件是干什么的，最后给一张速查表。你要是刚把主题拉下来、不知道从哪下手，看完这篇应该能少翻几遍文档。

先记住：这个站是两个仓库#

仓	放什么	改动频率
代码仓 `Shirone`	主题源码、构建脚本、测试、文档	一年动几次
内容仓 `shirone-content`	文章、说说、配置、图片	天天动

两个仓并排放：

1
E:\jisuanji\PycharmProjects\
2
├── Shirone\            代码仓
3
└── shirone-content\    内容仓

代码仓根目录里放一个清单文件，告诉构建内容在哪：

1
{
2
  "schemaVersion": 1,
3
  "source": {
4
    "type": "path",
5
    "path": "../shirone-content"
6
  }
7
}

有了它，pnpm dev 和 pnpm build 会先把内容仓物化到代码仓的对应位置，再开始构建。物化关系是固定的：

内容仓	物化到代码仓	说明
`content/`	`src/content/`	直接拷贝
`data/`	`src/data/`	直接拷贝
`assets/`	`src/assets/`	直接拷贝，构建期参与图片优化
`public/`	`public/`	直接拷贝，原样进 `dist/`
`config/`	编译进 `src/user/user-config.ts`	不拷贝，YAML 编译成 TypeScript 再和默认值深合并

WARNING

config/ 那一行是关键。「物化」这个词听着像拷文件，但配置不是拷贝，是编译。

所以手改完内容仓的 YAML 就去刷浏览器，读到的还是上一次编译出来的 src/user/user-config.ts。症状是改动看起来没生效，或者列表顺序既不是新的也不是旧的。补一次同步就好：

1
pnpm content:sync

代码仓：主题和构建都在这#

顶层#

astro.config.mjs构建总开关：集成、插件、Vite、字体
src主题源码，唯一的正文
scripts构建辅助脚本（图标、字体、图片、内容同步）
public原样拷贝的静态文件
tests端到端测试（Playwright）
docs主题开发文档，26 篇
rules硬规矩：无障碍、性能、组件 API、常见陷阱
artifacts检查产物（Lighthouse 报告）
.github/workflowsCI 与部署流水线
shirone.content.json指向内容仓
content.lock.json上次同步的锁定记录（源 commit + 各挂载点文件数）
package.json脚本入口
pnpm-lock.yaml依赖锁定
svelte.config.jsSvelte 编译器配置
tsconfig.jsonTypeScript 配置
biome.json代码检查与格式化规则
frontmatter.json编辑器扩展 Front Matter 的配置（可视化改 frontmatter 用）
pagefind.yml离线全文搜索的索引配置
playwright.config.ts端到端测试配置
lighthouserc.cjs性能检查的阈值配置
vercel.json部署平台配置（主题自带，本项目没用）
AGENTS.md给 AI 助手的项目说明
DESIGN.md设计规范
INDEX.md部署分层索引
README.md / CONTRIBUTING.md / LICENSE

`src/`：主题源码#

config27 个配置域，注释即文档
pages一个文件 = 一个网址
layouts页面骨架
components按原子化分层：atoms / molecules / organisms / content / system
pluginsMarkdown 扩展（提示框、图片网格、剧透、Mermaid……）
utils工具模块，69 个
styles全局样式与设计令牌
i18n界面文案，10 种语言
integration内容分离与配置叠加的集成逻辑
constants常量与图标名映射
types类型定义
content.config.ts集合与 frontmatter 字段定义
content← 内容仓物化来的文章
data← 内容仓物化来的数据
user← 内容仓物化来的配置（user-config.ts）
generated图标清单（local-icon-collections.ts）
assets← 内容仓物化来的图片

后面四个打箭头的，是生成物，全都在 .gitignore 里。这意味着一件事：

纯内容改动（写文章、改配置、换图）在代码仓里不需要提交任何东西。

只有动 src/ 里的主题源码才需要提交，因为那是唯一真正属于代码仓的部分。

`src/config/`：27 个配置域#

这是我最常用到的一个目录。主题把所有可配的东西拆成 27 个领域，每个领域一个文件，注释即文档。

文件	管什么
`siteConfig.ts`	站点核心：标题、语言、主题色、横幅、目录、进度条、favicon
`profileConfig.ts`	博主资料：头像、昵称、简介、社交链接
`navBarConfig.ts`	顶部导航与下拉子菜单
`sidebarConfig.ts`	侧栏布局与组件编排
`postListConfig.ts`	文章列表的分页大小与排版（列表 / 网格）
`articleConfig.ts`	文章详情页：更新提示、延伸阅读、分享与海报
`categoryConfig.ts`	分类的展示顺序
`permalinkConfig.ts`	文章永久链接格式
`commentConfig.ts`	评论系统（Twikoo / Giscus），默认关
`umamiConfig.ts`	访问统计，默认关
`musicConfig.ts`	侧栏音乐播放器，默认关
`animeConfig.ts`	追番页数据源（本地 / Bangumi / Bilibili）
`fontConfig.ts`	全站正文、中文、等宽字体
`openingAnimationConfig.ts`	首页开场动画，默认关
`footerConfig.ts`	页脚自定义 HTML 注入开关
`announcementConfig.ts`	侧栏公告栏，显示与否由 `sidebarConfig` 控制
`licenseConfig.ts`	文章底部版权协议
`expressiveCodeConfig.ts`	代码块高亮主题
`contextMenuConfig.ts`	桌面端右键菜单
`fabConfig.ts`	右下角悬浮按钮
`imageBloomConfig.ts`	图片加载时的色调辉光占位
`skillsConfig.ts` / `projectsConfig.ts` / `timelineConfig.ts` / `devicesConfig.ts`	四个数据页的展示规则
`llmsConfig.ts`	`/llms.txt` 与 `/llms-full.txt` 的生成
`index.ts`	统一出口，消费方一律从 `@/config` 导入

这里有个规律值得单独说，主题在文档里反复强调：配置管行为，数据管内容。

拿技能页举例。skillsConfig.ts 决定这个页面长什么样、分组按什么顺序展示；而具体有哪些技能、熟练度多少，在内容仓的 data/skills.ts 里。两个文件分在两个仓，各管各的。

`src/pages/`：一个文件就是一个网址#

不用配路由。文件路径就是 URL。

index（由 […page].astro 承担）/
[…permalink].astro自定义永久链接的出口
posts文章详情
archive.astro/archive/
categories.astro / tags.astro
about.astro / friends.astro / friends/apply.astro
albums.astro / moments.astro / skills.astro / projects.astro
compass.astro / devices.astro / timeline.astro / anime.astro
wip.astro一个占位页，彩蛋性质
rss.xml.ts / atom.xml.ts订阅源
llms.txt.ts / llms-full.txt.ts给 AI 读的纯文本版本
robots.txt.ts
404.astro

内容仓：你天天要动的都在这#

config26 个 YAML，只有 7 个在生效（下面解释）
content
- posts文章
- moments说说
- spec独立页面的正文，如 about.md
- snippets可被文章引用的片段
data友链、项目、技能、时间线、设备、追番、音乐、罗盘
assets会被优化的图片
public原样拷贝的静态资源
.github/workflows/trigger-build.yml推送后通知代码仓重新构建
小不悔个人博客改造我自己的工作笔记，不参与物化
README.md仓库地图（不参与物化）

`config/`：26 个 YAML，只有 7 个在生效#

状态	文件
生效中	`site.yaml`、`profile.yaml`、`nav-bar.yaml`、`sidebar.yaml`、`category.yaml`、`opening-animation.yaml`、`skills.yaml`
参考清单	其余 19 个，全文注释状态，不覆盖任何默认值

这不是偷懒，是有意的。主题的设计是「只写想改的键，其余跟随默认值」，这样主题升级时新的默认值能自动生效。把所有键写死，等于把配置冻结在当前版本，以后主题的改进就进不来了。

参考清单的作用是当备忘：想开评论，就去 comment.yaml 删掉行首的 # ，填上自己的参数。文件头写了两行说明，照着做就行。

`content/`：文章与说说#

目录	放什么
`posts/`	文章，`.md` 或 `.mdx`。支持子目录归类，`posts/guide/x.md` 的网址就是 `/posts/guide/x/`
`moments/`	说说，短内容，时间流展示
`spec/`	独立页面正文，`about.md` 对应「关于」页
`snippets/`	可被文章引用的公共片段

我现在的文章按分类分了四层目录：guides/、examples/、musings/、blog-rework-diary/。文件名全用拼音，这样 URL 里全是 ASCII。

`data/`：页面数据实体#

这里放具体条目，对应的 config/*.yaml 只管页面开关和排序。

文件	内容
`friends.ts`	友情链接
`projects.ts`	开源项目
`skills.ts`	技能清单与熟练度
`timeline.ts`	大事记
`devices.ts`	设备清单
`anime.ts`	本地番剧清单
`music.ts`	本地曲目
`compass.ts` / `compass-other.ts`	罗盘（导航）条目
`custom-icons.ts`	图标登记表，写 YAML 图标时必须同步这里

每个文件顶部都有中文注释，照着已有条目复制改就行。

`assets/` 和 `public/` 的区别#

	`assets/`	`public/`
物化到	代码仓 `src/assets/`	代码仓 `public/`
构建处理	会压缩、生成响应式尺寸	原样拷贝
引用方式	相对路径或 `import`	`/` 开头的绝对路径
适合放	头像、首页横幅、音乐封面	相册图、说说配图、favicon

我想改 X，应该去哪#

我想……	去哪
改站点标题 / 副标题 / 语言 / 时区	内容仓 `config/site.yaml`
改主题色、背景纹理、首页横幅	内容仓 `config/site.yaml`
改昵称 / 头像 / 签名 / 社交链接	内容仓 `config/profile.yaml`
写文章	内容仓 `content/posts/` 新建文件
发说说	内容仓 `content/moments/` 新建文件
改「关于」页	内容仓 `content/spec/about.md`
加友链	内容仓 `data/friends.ts`
加项目 / 技能 / 时间线 / 设备	内容仓 `data/` 下对应文件
换横幅图、头像图	内容仓 `assets/images/`
换相册图、说说配图	内容仓 `public/images/`
改侧栏组件	内容仓 `config/sidebar.yaml`
改导航菜单	内容仓 `config/nav-bar.yaml`
改分类顺序	内容仓 `config/category.yaml`
开评论 / 统计 / 音乐	内容仓 `config/` 下对应文件，取消注释
改页面固定文案（“阅读更多”这类）	代码仓 `src/i18n/`
改组件结构、布局、CSS	代码仓 `src/`（改之前先想清楚）

小结#

两份仓库，一张 shirone.content.json 把它们接起来。日常只在内容仓里干活。
内容仓里 config/ 管行为、data/ 管内容、content/ 管文字、assets/ 和 public/ 管图。
代码仓的 src/config/ 是配置的默认值说明书，注释即文档，查某个键什么意思去那里。
src/content/、src/data/、src/user/、src/generated/、src/assets/ 是生成产物，别手改，也不进版本库。

改造记到这里就写完了。前面几篇讲怎么把别人的站改成自己的，这篇讲改完之后它到底长什么样。后面如果还有想写的，大概是部署上线那一段的事。

xiaobuhui

先记住：这个站是两个仓库#

代码仓：主题和构建都在这#

顶层#

`src/`：主题源码#

`src/config/`：27 个配置域#

`src/pages/`：一个文件就是一个网址#

内容仓：你天天要动的都在这#

`config/`：26 个 YAML，只有 7 个在生效#

`content/`：文章与说说#

`data/`：页面数据实体#

`assets/` 和 `public/` 的区别#

我想改 X，应该去哪#

小结#

继续阅读

换条路线

xiaobuhui

先记住：这个站是两个仓库#

代码仓：主题和构建都在这#

顶层#

src/：主题源码#

src/config/：27 个配置域#

src/pages/：一个文件就是一个网址#

内容仓：你天天要动的都在这#

config/：26 个 YAML，只有 7 个在生效#

content/：文章与说说#

data/：页面数据实体#

assets/ 和 public/ 的区别#

我想改 X，应该去哪#

小结#

分享文章

沿着主题读

换条路线

`src/`：主题源码#

`src/config/`：27 个配置域#

`src/pages/`：一个文件就是一个网址#

`config/`：26 个 YAML，只有 7 个在生效#

`content/`：文章与说说#

`data/`：页面数据实体#

`assets/` 和 `public/` 的区别#