站点壳与其它组件§
components/site/site-header.tsx§
客户端：用 usePathname 判断「文章 / 系列 / 标签」哪一项高亮；右侧嵌 ThemeToggle，并展示静态站状态点文案。
components/site/theme-toggle.tsx§
系统 / 浅色 / 深色三态，基于 useTheme()。同样有挂载门闩，避免主题未恢复时闪错图标。
列表与系列 UI§
| 组件 | 用途 |
|---|---|
components/posts/post-card.tsx | 散篇卡片（可嵌 ReadingChip） |
components/series/series-card.tsx | 小册卡片（首页 / /series） |
components/series/series-toc.tsx | 小册首页大目录 + ChapterPager |
components/series/series-chapter-rail.tsx | 章节页左侧本册导轨 |
components/series/series-chapter-strip-client.tsx | 窄屏横向切章（仅 import series-path） |
components/reading/reading-chip.tsx | 按 progressKey 显示已读百分比 |
components/site/site-footer.tsx§
页脚链到系列小册与全部标签。
app/styles/：设计系统落在哪§
app/globals.css 只做聚合导入；样式按域拆在 app/styles/：
tokens.css：@theme与深/浅语义 RGBbase.css：页面底色、选区等site.css：通用壳、系列三栏、入口动效、主题切换prose.css/code.css/reading.css/photos.css：对应领域组件类
系列三栏相关样式要点：
.series-chapter-frame大屏三列；默认 stretch.series-chapter-sticky：top: 5.5rem+max-height+ 内部滚动.series-rail*：本册导轨、当前章竖条高亮、册内进度条.series-strip*：窄屏横向芯片（约 <1080px 显示，大屏隐藏）
颜色策略：朱红（accent）几乎只用于链接、焦点与进度；jade 用于在线状态点。
排版专题见散篇《建站四问》。
客户端边界（系列踩过的坑）§
会 fs.readFile 的 lib/series.ts 不能被 "use client" 模块直接引用。横向章节条只从 lib/series-path.ts 取 chapterHref / seriesHref。否则 Turbopack 会在打包客户端时报「不支持 external modules (node:fs)」。
scripts/ 与 types/§
scripts/screenshot.mjs、theme-shot.mjs：可选的 Playwright 截图巡检types/prism*.d.ts：给 Prism 副作用导入补类型
设计取舍（对应到代码位置）§
- 文件即内容库——散篇
lib/posts.ts，小册lib/series.ts；换 CMS 等于重写这两层。 - 散篇与系列并列目录——不用 frontmatter 硬塞「系列字段」，URL 与静态参数更直观。
- 目录 id 双端同源——
extractToc与rehype-slug共用 GitHub 风格 slug。 - 客户端下沉——页面主体仍是服务端组件；进度、代码块、主题、横向章节条等才标
"use client"。 - 进度只存历史——
partialize只持久化history；系列用带前缀的progressKey。 - 路径辅助与读盘拆分——
series-path.ts可进客户端；series.ts只在服务端。 - 长文进系列——避免首页时间线被超长单篇淹没。
- 沙箱默认不给 same-origin——预览能跑脚本，不易直接碰父页面 DOM。
改功能时打开哪扇门§
| 你想改的事 | 优先打开的文件 |
|---|---|
| 新增 / 修改散篇 | content/posts/*.mdx |
| 新增一册小册 | content/series/{册}/series.json + 各章 .mdx |
| 修改本册某一章 | content/series/{册}/*.mdx |
| 字数算法、刊号 | lib/posts.ts |
| 标签聚合（posts + series） | lib/tags.ts |
| 系列索引、章序、progressKey | lib/series.ts |
| 系列 URL 拼接（含客户端） | lib/series-path.ts |
| MDX 插件顺序或编译入口 | lib/mdx.tsx |
| 代码围栏合并、高亮写入 AST | lib/rehype.ts（概览见「rehype 源码」；rehypeCodeGroups 逐步执行见扩展篇） |
| 支持更多高亮语言 | lib/prism.ts + lib/code-lang.ts |
| Callout、标题锚点、表格包裹 | components/mdx/index.tsx |
| Tab / 复制 / 沙箱 | components/mdx/code-block.tsx |
| 顶部进度条手感 | components/reading/progress-bar.tsx |
| 本章折线 / 手机目录 | components/reading/reading-path.tsx |
| 进度存储策略 | components/reading/store.ts |
| 继续阅读芯片时机 | components/reading/article-shell.tsx |
| 本册左侧导轨 | components/series/series-chapter-rail.tsx |
| 窄屏横向切章 | components/series/series-chapter-strip-client.tsx |
| 小册列表卡片 | components/series/series-card.tsx |
| 小册首页目录 | components/series/series-toc.tsx |
| 章已读百分比 | components/reading/reading-chip.tsx |
| 首页结构（含系列区块） | app/page.tsx |
| 散篇版式 | app/posts/[slug]/page.tsx |
| 系列列表 / 小册封面 | app/series/page.tsx、app/series/[series]/page.tsx |
| 章节三栏阅读台 | app/series/[series]/[chapter]/page.tsx |
| 三栏 / 导轨 / 横条外观 | app/styles/site.css（搜索 series-chapter） |
| 顶栏「系列」导航 | components/site/site-header.tsx |
| 站点名、日期、站点 URL | lib/site.ts |
| sitemap / robots | app/sitemap.ts、app/robots.ts |
本册是「对着仓库读」的地图，不是替代各专题散篇：代码围栏作者语法、进度动效动机、颜色与字体取舍，仍以对应散篇为准。系列版块的内容模型与 API 细节，以「系列小册」那一章为准；页面挂载与 sticky 约定，以「页面与路由」那一章为准。