docs: 更新文档

README.md

@@ -45,6 +45,36 @@
 <details>
 <summary>点击查看/隐藏更新日志</summary>
 
+### 2025/12/27
+
+细节见：[`config/update-instructions-20251227.md`](config/update-instructions-20251227.md)
+
+**1. 页面模板差异化改进（Phase 1/Phase 2）**
+- 首页判定规则调整：`site.yml -> navigation` 第一项即首页（不再依赖 `home` 页面/ID）
+- 模板体系整理：通用 `page` + 特殊页 `projects/articles/bookmarks` + 内置 `search-results`
+- `bookmarks` 标题后追加只读更新时间：`update: YYYY-MM-DD | from: git|mtime`
+- `articles` Phase 2：RSS 聚合文章条目（只读 `data-type="article"`），按 `articles.yml` 分类聚合展示；保留隐藏写回结构避免干扰扩展
+- `projects`：repo 风格卡片（language/stars/forks 自动抓取）+ 可选 GitHub 贡献热力图
+
+**2. 工作流与时效性数据刷新**
+- GitHub Actions 构建前自动执行 `sync-projects` / `sync-articles`
+- 新增 `schedule` 定时触发刷新（cron 使用 UTC，可在 workflow 中调整）
+
+**3. 配置与兼容清理（Breaking）**
+- 移除旧版单文件配置 `config.yml/config.yaml` 回退
+- 移除独立 `navigation.yml` 回退
+- 移除 `pages/home.yml -> 顶层 categories` 与 `home` 子菜单特例
+- `navigation[].active` 不再生效（首页/默认打开页始终由 `navigation` 第一项决定）
+
+**4. 配置变更（字段新增/减少）**
+- 新增：
+  - `site.rss.*`：articles RSS 抓取与缓存配置（用于 `npm run sync-articles`）
+  - `site.github.*`：projects 热力图与仓库元信息抓取缓存配置（用于 `npm run sync-projects`）
+  - `pages/<id>.yml -> template`：页面模板选择（缺省时按回退规则使用 `page`）
+- 说明：
+  - “首页”始终由 `site.yml -> navigation` 第一项决定，不要求页面 id 为 `home`
+
+
 ### 2025/12/23
 
 **1. 侧边栏与导航交互优化**
@@ -209,6 +239,7 @@ menav/
 
 ## 文档导航
 
+- 更新说明2025/12/27（兼容性移除 / 迁移指南）：[`config/update-instructions-20251227.md`](config/update-instructions-20251227.md)
 - 配置系统（完全替换策略、目录结构、示例）：[`config/README.md`](config/README.md)
 - 书签导入（格式要求、流程、常见问题）：[`bookmarks/README.md`](bookmarks/README.md)
 - 模板系统（组件、回退、数据流）：[`templates/README.md`](templates/README.md)

config/update-instructions-20251227.md

@@ -0,0 +1,103 @@
+# 更新说明（2025-12-27）
+
+本文档用于说明“页面模板差异化改进”相关改动中，**配置层面的新增字段、减少字段与迁移要点**。内容与 [`README.md`](../README.md) 的“2025/12/27 更新记录”保持一致。
+
+最后更新：2025-12-27
+
+---
+
+## 1. 新增/扩展的配置字段
+
+### 1.1 `site.rss.*`（articles RSS 聚合 / 缓存）
+
+用途：为 `articles` 页面提供 RSS/Atom 文章聚合数据，供 `npm run sync-articles` 联网抓取并写入缓存；`npm run build` 默认不联网，只读取缓存渲染。
+
+关键字段（默认示例见 `config/_default/site.yml`）：
+- `site.rss.enabled`：是否启用 RSS 抓取能力
+- `site.rss.cacheDir`：缓存目录（建议 `dev/`，仓库默认 gitignore）
+- `site.rss.fetch.*`：抓取参数（超时、并发、重试、重定向等）
+- `site.rss.articles.*`：抓取条数与摘要长度（例如每站点最多 8 篇）
+
+说明：
+- RSS 抓取只影响 `articles` Phase 2（文章条目只读展示），不会影响扩展对“来源站点（sites）”的写回能力（构建会保留影子写回结构）。
+
+---
+
+### 1.2 `site.github.*`（projects 仓库元信息 + 热力图）
+
+用途：
+- projects 卡片可展示仓库元信息（language/stars/forks 等，只读），由 `npm run sync-projects` 联网抓取并写入缓存。
+- projects 标题区右侧可选展示 GitHub 贡献热力图。
+
+关键字段（默认示例见 `config/_default/site.yml`）：
+- `site.github.username`：GitHub 用户名；为空则不展示热力图
+- `site.github.heatmapColor`：热力图主题色（不带 `#`，如 `339af0`）
+- `site.github.cacheDir`：仓库元信息缓存目录（建议 `dev/`）
+
+说明：
+- 仓库元信息来自 GitHub API，属于“时效性数据”，不会写回到 `pages/projects.yml`。
+
+---
+
+### 1.3 `pages/<id>.yml -> template`（页面模板选择）
+
+用途：指定页面使用的模板（对应 `templates/pages/<template>.hbs`，不含扩展名）。
+
+行为规则：
+- 若 `template` 缺省：优先尝试同名模板（`templates/pages/<pageId>.hbs`），不存在则回退到通用 `page` 模板。
+- `bookmarks/projects/articles` 等特殊页建议显式配置 `template`，以减少误解。
+
+---
+
+## 2. 减少/不再支持的配置方式（Breaking）
+
+### 2.1 根目录单文件配置 `config.yml` / `config.yaml`
+
+当前版本不再回退读取根目录 `config.yml`/`config.yaml`。
+
+迁移要点：
+- 使用模块化配置目录：`config/user/`（优先级最高，完全替换）或 `config/_default/`（默认示例）。
+- 推荐迁移方式：复制 `config/_default/` → `config/user/`，再按需修改 `site.yml` 与 `pages/*.yml`。
+
+---
+
+### 2.2 独立 `navigation.yml`
+
+当前版本仅从 `site.yml -> navigation` 读取导航配置，不再读取 `navigation.yml`。
+
+迁移要点：
+- 将原 `navigation.yml` 的数组内容移动到 `config/user/site.yml` 的 `navigation:` 字段下。
+
+---
+
+### 2.3 `pages/home.yml -> 顶层 categories` 与 `home` 子菜单特例
+
+当前版本不再维护“首页固定叫 `home`”的遗留逻辑（例如把 `pages/home.yml` 的分类提升到顶层 `config.categories`）。
+
+迁移要点：
+- 不要依赖固定页面 id `home`。
+- 首页始终由 `site.yml -> navigation` 的**第一项**决定；其分类内容应写在对应的 `pages/<homePageId>.yml` 中。
+
+---
+
+### 2.4 `navigation[].active` 不再生效（首页不再靠 active 指定）
+
+历史版本可能通过 `navigation[].active` 指定“默认打开页/首页”。
+
+当前版本：
+- 首页/默认打开页始终由 `site.yml -> navigation` 的**第一项**决定
+- `active` 字段将被忽略（即使写了也不会生效）
+
+迁移要点：
+- 通过调整 `navigation` 数组顺序来设置首页（把希望作为首页的页面放到第一项）。
+
+---
+
+## 3. 与更新记录的对应关系（快速索引）
+
+- 首页判定规则：`site.yml -> navigation` 第一项
+- 模板体系：`pages/<id>.yml -> template`（缺省回退 `page`）
+- bookmarks 更新时间：构建期注入（不需要新增配置字段）
+- articles RSS：`site.rss.*` + `npm run sync-articles`
+- projects 元信息/热力图：`site.github.*` + `npm run sync-projects`
+- 兼容清理：移除 `config.yml/config.yaml`、`navigation.yml`、`home` 特例

config/update-instructions.md

@@ -1,59 +0,0 @@
-# 更新说明（兼容性移除 / 迁移指南）
-
-本文档说明本次“页面模板差异化改进”阶段，在配置/构建链路上**移除的历史兼容行为**以及如何迁移。
-
-最后更新：2025-12-27
-
----
-
-## 1. 已移除的兼容行为（Breaking）
-
-### 1.1 不再支持旧版单文件配置 `config.yml` / `config.yaml`
-
-- 旧版本在未发现 `config/user/` 与 `config/_default/` 时，会回退读取根目录的 `config.yml` / `config.yaml`。
-- 当前版本：仅支持模块化配置目录：
-  - `config/user/`（优先级最高，完全替换）
-  - `config/_default/`（默认示例）
-
-迁移要点：
-- 如果你只有 `config.yml`/`config.yaml`：请将其内容拆分到 `config/user/site.yml` 与 `config/user/pages/*.yml`。
-- 推荐做法：先复制一份默认示例，再按需替换字段：
-  1) 复制 `config/_default/` → `config/user/`
-  2) 修改 `config/user/site.yml`、`config/user/pages/*.yml`
-
----
-
-### 1.2 不再支持独立 `navigation.yml`
-
-- 旧版本可能存在 `config/user/navigation.yml`（或 `_default/navigation.yml`）作为导航配置来源。
-- 当前版本：导航仅从 `site.yml -> navigation` 读取；不再回退读取独立 `navigation.yml`。
-
-迁移要点：
-- 把原 `navigation.yml` 的数组内容移动到 `config/user/site.yml` 的 `navigation:` 字段下。
-- 书签导入流程也只会更新 `config/user/site.yml`，不会再尝试写入/更新 `navigation.yml`。
-
----
-
-### 1.3 不再支持 `pages/home.yml -> 顶层 config.categories` 与 `home` 子菜单特例
-
-- 旧版本存在“首页写死叫 `home`”的遗留逻辑：
-  - 若存在 `pages/home.yml`，会把其 `categories` 复制到顶层 `config.categories`
-  - 生成导航子菜单时，若 `nav.id === 'home'`，会优先从 `config.categories` 取分类
-- 当前版本：不再维护上述特殊字段/特例；子菜单统一从 `pages/<id>.yml` 的 `categories` 读取。
-
-迁移要点：
-- 不要依赖 `home` 这个固定 id。
-- 首页始终由 `site.yml -> navigation` 的**第一项**决定；其分类应写在对应的 `pages/<homePageId>.yml` 中。
-
----
-
-## 2. 快速迁移清单（建议按顺序执行）
-
-1. 确保存在 `config/user/site.yml`
-2. 确保 `config/user/site.yml` 内包含 `navigation:`（数组）
-3. 确保每个 `navigation[].id`（除内置 `search-results`）都有对应的 `config/user/pages/<id>.yml`（可缺省，但缺省时页面内容为空）
-4. 若你曾使用 `config.yml/config.yaml`：将其内容迁移到模块化目录
-5. 若你曾使用 `navigation.yml`：迁移到 `site.yml -> navigation`，并删除 `navigation.yml`（可选）
-
-> 提示：配置采用“完全替换”策略，一旦存在 `config/user/` 就不会回退到 `config/_default/` 补齐缺失项。
-