Astro 内容站：组件组合重构、重复代码清理与文档同步

这轮重构的重点，不是“做一个新页面”，而是把已经长出来的重复结构彻底收一次。

目标很明确：

1. 去掉无效和重复代码
2. 让单个页面更多只是组装组件
3. 让新增组件各自有文档
4. 让旧文档回到和当前实现一致

第一类：页面骨架重复

最先收口的是页面骨架层。

原来的问题是：

• 很多页面都自己写一份 page-hero
• 首页、归档、系列和索引分组都自己写一份 page-section-header
• 归档总览卡完全内联在页面里

这次的处理方式是新增 3 个组件：

• PageHero
• PageSectionHeader
• SummaryStatGrid

这样页面文件开始回到“组合层”的位置：

• 页面负责数据和文案
• 小组件负责结构和样式

第二类：分页链接重复

分页页本来都在重复做一件事：

1. 调 getPaginationSlots
2. map 成 pageLinks
3. 把 href / current / label 再拼一遍

这类代码在文章页、归档页、系列页、系列详情页里都在重复。

所以这次把它提成了 lib/pagination.ts 里的 helper：

• getPaginationPageLinks(...)

结果是页面文件不再关心“slot 怎么变成 link”，只关心“这一页的路径怎么生成”。

第三类：页面文件过重

重构前，很多 page view 组件已经不是逻辑复杂，而是结构噪音太多。

例如：

• 首页同时写 hero、section header、卡片区
• 归档页同时写 hero、summary heading、summary cards、pagination
• 系列详情页同时写 header、section heading、章节 shelf、pagination

这些结构拆出去之后，page view 更接近它应有的形态：

• 接收 props
• 准备数据
• 选择 copy
• 组装组件

这也是“单独组件单独文件”的真正收益。不是文件越多越好，而是让每个文件只承担一种明显职责。

第四类：旧文档漂移

结构重构之后，最容易坏掉的不是构建，而是技术文章。

这轮一起处理了两种文档：

• 给新增组件补独立文章
• 给已经受影响的旧文章补同步修改

这一步很重要，因为内容站里“文档过期”本身也是结构债务。
如果文章继续描述旧实现，仓库会很快出现两套真相：

• 代码里的真相
• 文章里的真相

后面回头看时，判断成本会越来越高。

这次重构后的组织方式

这轮之后，页面组合大致稳定成了下面几层：

• layout/* 页面骨架、hero、section header、header、theme
• content/* 卡片列表、索引列表、分页、统计卡
• pages/* 负责页面装配
• lib/* 负责内容读取、排序、分页和 view-model 辅助

这套拆法的关键不在“目录看起来更整齐”，而在于新增功能时更容易判断：

• 这是页面骨架问题
• 这是内容组件问题
• 这是数据整理问题
• 还是只是文案变化

为什么这一步要和文档同步一起做

如果只做组件重构，不做文章同步，仓库很快又会回到一种半旧半新的状态。

所以这次不是“先改代码，文档以后再补”，而是把它当成同一个任务处理：

• 新增组件就补单独文章
• 大范围改动就补总文章
• 已受影响的旧文章也一起修

这样做虽然慢一点，但能让整个站点在结构层和叙述层同时收口。