feat: 页面模板差异化改进 + 配置优化 + 兼容清理 (#29)

- 首页判定：navigation 第一项 - 模板：page/projects/articles/bookmarks/search-results - bookmarks：update: YYYY-MM-DD | from: git|mtime - articles：RSS 聚合只读条目 + 分类聚合 + 影子写回结构 - projects：repo 卡片 + 可选热力图 + 自动抓取元信息 - 工作流：构建前 sync + schedule 定时刷新 - 移除兼容：config.yml/config.yaml、navigation.yml、home 特例 - 迁移说明：config/update-instructions.md
2025-12-28 00:22:54 +08:00
parent 1475a8a0d3
commit 387cd2492e
35 changed files with 2927 additions and 851 deletions
--- a/config/README.md
+++ b/config/README.md
@@ -30,15 +30,14 @@ config/
 ├── _default/           # 默认配置目录
 │   ├── site.yml        # 默认网站基础配置（含导航配置）
 │   └── pages/          # 默认页面配置
-│       ├── home.yml    # 首页默认配置
-│       ├── projects.yml
-│       ├── articles.yml
-│       ├── friends.yml
-│       └── bookmarks.yml
+│       ├── common.yml   # 示例：默认首页（navigation 第一项）
+│       ├── projects.yml # 项目页
+│       ├── articles.yml # 文章页
+│       └── bookmarks.yml # 书签页
 └── user/               # 用户配置目录（覆盖默认配置）
    ├── site.yml        # 用户自定义网站配置（含导航配置）
    └── pages/          # 用户自定义页面配置
-        ├── home.yml    # 首页用户配置
+        ├── common.yml  # 示例：与 navigation 第一项对应
        └── ...
 ```

@@ -74,18 +73,17 @@ MeNav 配置系统采用“完全替换”策略（不合并），按以下优
 - 个人资料和社交媒体链接
 - 导航菜单配置（侧边栏导航项、页面标题和图标、页面顺序和可见性）

-> **注意**：从 v1.x 版本开始，导航配置已合并到 `site.yml` 文件中，不再使用独立的 `navigation.yml` 文件。如果您从旧版本迁移，请将原 `navigation.yml` 的内容移至 `site.yml` 的 `navigation` 字段下。
+> **注意**：导航配置仅支持写在 `site.yml` 的 `navigation` 字段中。

 ### 页面配置

 `pages/` 目录下的配置文件定义各个页面的内容：

- `home.yml`: 首页分类和站点列表
+- `common.yml`: 示例首页（本质上是普通页面；首页由 navigation 第一项决定，不要求必须叫 home）
 - `projects.yml`: 项目展示配置
 - `articles.yml`: 文章列表配置
- `friends.yml`: 友情链接配置
 - `bookmarks.yml`: 书签页面配置
- 自定义页面配置
+- 其他自定义页面配置（可按需新增/删除；与 `site.yml -> navigation[].id` 对应）

 ## 配置详解

@@ -120,23 +118,63 @@ MeNav 配置系统采用“完全替换”策略（不合并），按以下优
   - `profile.title` / `profile.subtitle`：分别对应首页顶部主标题与副标题

 5. **导航**
-   - `navigation[]`：页面入口列表，`id` 需唯一，并与 `pages/` 中配置文件名对应（例如 `id: home` 对应 `pages/home.yml`）
+   - `navigation[]`：页面入口列表，`id` 需唯一，并与 `pages/<id>.yml` 对应（例如 `id: common` 对应 `pages/common.yml`）
   - 默认首页由 `navigation` 数组顺序决定：**第一项即为首页（默认打开页）**，不再使用 `active` 字段
   - 图标使用 Font Awesome 类名字符串（例如 `fas fa-home`、`fab fa-github`）
   - 导航显示顺序与数组顺序一致，可通过调整数组顺序改变导航顺序

+6. **RSS（articles Phase 2）**
+   - `rss.*`：仅用于 `npm run sync-articles`（联网抓取 RSS/Atom 并写入缓存）
+   - `npm run build` 默认不联网；无缓存时 `articles` 页面会回退到 Phase 1 的站点入口展示
+   - articles 页面会按 `articles.yml` 的分类进行聚合展示：某分类下配置的来源站点，其文章会显示在该分类下
+   - 抓取条数默认：每个来源站点抓取最新 8 篇（可通过 `site.yml -> rss.articles.perSite` 或 `RSS_ARTICLES_PER_SITE` 调整）
+   - 默认配置已将 `rss.cacheDir` 设为 `dev`（仓库默认 gitignore），避免误提交缓存文件；可按需改为自定义目录
+   - GitHub Pages 部署工作流会在构建前自动执行 `npm run sync-articles`，并支持定时触发（默认每天 UTC 02:00；可在 `.github/workflows/deploy.yml` 调整）
+
+7. **GitHub（projects 热力图，可选）**
+   - `github.username`：你的 GitHub 用户名（用于 projects 页面标题栏右侧贡献热力图）
+   - `github.heatmapColor`：热力图主题色（不带 `#`，例如 `339af0`）
+   - `github.cacheDir`：projects 仓库元信息缓存目录（默认 `dev`，仓库默认 gitignore）
+   - projects 仓库统计信息（language/stars/forks）由 `npm run sync-projects` 自动抓取并写入缓存；`npm run build` 默认不联网
+   - GitHub Pages 部署工作流会在构建前自动执行 `npm run sync-projects`，并支持定时触发（默认每天 UTC 02:00；可在 `.github/workflows/deploy.yml` 调整）
+
 ### pages/ 页面配置

 页面配置位于 `pages/*.yml`，每个文件对应一个页面内容，文件名与导航 `id` 对应：

- `pages/home.yml`：首页（通常是 `categories -> sites`）
- `pages/projects.yml` / `articles.yml` / `friends.yml`：示例页面（可按需删改）
+- `pages/common.yml`：示例首页（通常是 `categories -> sites`）
+- `pages/projects.yml` / `articles.yml`：示例页面（可按需删改）
 - `pages/bookmarks.yml`：书签页（通常由导入脚本生成，也可以手动维护）

 > 提示：自定义页面时，先在 `site.yml` 的 `navigation` 中增加一个 `id`，再创建同名的 `pages/<id>.yml`。
 >
+> 支持“可删除”：如果 `navigation` 中存在某个页面 `id`，但 `pages/<id>.yml` 不存在，构建仍会生成该页面（标题回退为导航名称、分类为空、模板默认使用通用 `page`）。
+>
 > 站点描述建议简洁（例如不超过 30 个字符），以保证卡片展示更美观。

+#### 通用 page 页面配置（推荐，用于 friends 等普通页面）
+
+对不需要特殊渲染的页面（例如“友链/朋友”页），建议使用通用 `page` 模板，并保持 `categories -> sites`（可选更深层级）：
+
+```yaml
+title: 示例页面
+subtitle: 示例副标题
+template: page
+
+categories:
+  - name: 示例分类
+    icon: fas fa-folder
+    sites:
+      - name: 示例站点
+        url: https://example.com
+        icon: fas fa-link
+        description: 示例描述
+```
+
+兼容说明：
+
+- 若历史配置仍使用顶层 `sites`（旧结构），系统会自动映射为一个分类容器以保持页面结构一致（当前仅对 friends/articles 提供该兼容）。
+
 ### 多层级嵌套配置（2-4层）

 书签与分类支持 2~4 层嵌套，用于更好组织大量站点。建议直接参考默认示例：
@@ -184,7 +222,6 @@ MeNav 配置系统采用“完全替换”策略：只会选择一套目录加

 - `site.yml`：站点全局配置（包含 `navigation` 等）
 - `pages/*.yml`：各页面配置（文件名需与 `navigation.id` 对应）
- `navigation.yml`：仅在 `site.yml` 未提供 `navigation` 时回退使用（兼容旧版本；推荐迁移到 `site.yml`）

 ## 配置示例

@@ -227,21 +264,24 @@ social:

 # 导航配置
 navigation:
-  - name: "首页"
-    icon: "fas fa-home"
-    id: "home"
+  - name: "常用"
+    icon: "fas fa-star"
+    id: "common"
  - name: "项目"
    icon: "fas fa-project-diagram"
    id: "projects"
  - name: "文章"
    icon: "fas fa-book"
    id: "articles"
+  - name: "书签"
+    icon: "fas fa-bookmark"
+    id: "bookmarks"
 ```

-### 首页配置示例 (home.yml)
+### 通用页面配置示例（例如 common.yml）

 ```yaml
-# 首页分类配置
+# 页面分类配置
 categories:
  - name: "常用工具"
    icon: "fas fa-tools"
--- a/config/_default/pages/articles.yml
+++ b/config/_default/pages/articles.yml
@@ -1,40 +1,43 @@
 # 默认页面配置（请勿直接修改）。
 # 建议复制到 config/user/pages/articles.yml 并按需调整。
 title: 技术文章                 # 页面标题
-subtitle: 分享我的技术文章和学习笔记  # 页面副标题
+subtitle: RSS 聚合文章列表  # 页面副标题

 # 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
 template: articles

-# 页面分类与站点列表
+# 当存在 RSS 缓存时，页面将优先渲染“文章条目卡片”（只读）。
+# - 本处的站点列表作为“来源站点”输入（url 填站点首页）
+# - 显示时会将“该分类下配置的站点”抓取到的文章聚合展示在该分类下
+# 重要：url 应填写“站点首页 URL”（不是某一篇文章链接），系统会自动发现 RSS/Atom。
 categories:
-  - name: 最新文章
-    icon: fas fa-pen  # 分类图标
+  - name: 个人博客
+    icon: fas fa-rss
    sites:
-      - name: Vue3最佳实践            # 站点名称
-        icon: fab fa-vuejs           # 文章/站点图标
-        description: Vue3组合式API的使用技巧  # 摘要
-        url: "#"                     # 链接（示例）
-      - name: JavaScript进阶
-        icon: fab fa-js
-        description: JavaScript高级特性解析
-        url: "#"
-      - name: Git使用技巧
-        icon: fab fa-git-alt
-        description: Git常用命令和工作流
-        url: "#"
-      - name: Docker入门
-        icon: fab fa-docker
-        description: Docker基础知识和实践
-        url: "#"
-  - name: 学习笔记
-    icon: fas fa-book
+      - name: 阮一峰的网络日志
+        icon: fas fa-pen
+        description: 技术文章与随笔
+        url: https://www.ruanyifeng.com/blog/
+      - name: Coolzr's Blog
+        icon: fas fa-pen
+        description: 偶尔会写点什么
+        url: https://blog.rzlnb.top/
+      - name: 天仙子
+        icon: fas fa-pen
+        description: tianxianzi
+        url: https://www.tianxianzi.me/
+      - name: pseudoyu
+        icon: fas fa-pen
+        description: pseudoyu
+        url: https://www.pseudoyu.com/
+  - name: 官方博客
+    icon: fas fa-rss
    sites:
-      - name: React Hooks
-        icon: fab fa-react
-        description: React Hooks最佳实践
-        url: "#"
-      - name: Node.js实战
-        icon: fab fa-node-js
-        description: Node.js服务端开发笔记
-        url: "#" 
+      - name: GitHub Blog
+        icon: fab fa-github
+        description: GitHub 官方博客（工程/产品/安全）
+        url: https://github.blog/
+      - name: Cloudflare Blog
+        icon: fas fa-cloud
+        description: Cloudflare 工程与安全博客
+        url: https://blog.cloudflare.com/
--- a/config/_default/pages/bookmarks.yml
+++ b/config/_default/pages/bookmarks.yml
@@ -1,10 +1,11 @@
 # 默认页面配置（请勿直接修改）。
 # 建议复制到 config/user/pages/bookmarks.yml 并按需调整。
 # 说明：该页面通常由“书签导入工具”自动生成，手工修改时请保持字段结构一致。
-title: 我的书签
-subtitle: 网页书签收藏
+title: 书签
+subtitle: bookmarks

 # 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
+# 提示：bookmarks 模板页面标题区会自动显示“内容更新：YYYY-MM-DD（git|mtime）”，无需额外配置
 template: bookmarks

 categories:
--- a/config/_default/pages/common.yml
+++ b/config/_default/pages/common.yml
@@ -1,15 +1,16 @@
 # 默认页面配置（请勿直接修改）。
-# 建议复制到 config/user/pages/home.yml 并按需调整。
-title: 欢迎使用        # 页面标题
-subtitle: 个人导航站点  # 页面副标题
+# 建议复制到 config/user/pages/common.yml 并按需调整。
+title: 常用网站        # 页面标题
+subtitle: Common website  # 页面副标题

 # 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
-template: home
+# 说明：推荐使用通用模板 page；首页由“导航第一项”决定
+template: page

-# 页面分类与站点列表（可按需增删顺序）
+# 页面分类与站点列表
 categories:
-  - name: 常用网站
-    icon: fas fa-star # 分类图标（Font Awesome）
+  - name: 置顶
+    icon: fas fa-star # 分类图标
    sites:
      - name: Linux.do            # 站点名称
        url: https://linux.do/    # http/https URL（favicon 模式将尝试加载站点图标）
@@ -50,10 +51,6 @@ categories:
        url: https://www.bilibili.com
        icon: fas fa-play-circle
        description: 视频学习平台
-      - name: 知乎
-        url: https://www.zhihu.com
-        icon: fas fa-question-circle
-        description: 问答社区
      - name: 掘金
        url: https://juejin.cn
        icon: fas fa-book
@@ -62,57 +59,6 @@ categories:
        url: https://leetcode.cn
        icon: fas fa-code
        description: 算法刷题平台
-      - name: Coursera
-        url: https://www.coursera.org
-        icon: fas fa-university
-        description: 在线课程平台
-      - name: edX
-        url: https://www.edx.org
-        icon: fas fa-graduation-cap
-        description: 高质量在线教育
-      - name: Udemy
-        url: https://www.udemy.com
-        icon: fas fa-chalkboard-teacher
-        description: 技能学习平台
-      - name: MDN Web Docs
-        url: https://developer.mozilla.org
-        icon: fas fa-file-code
-        description: Web开发文档
-  - name: 开发工具
-    icon: fas fa-tools
-    sites:
-      - name: VS Code
-        url: https://code.visualstudio.com
-        icon: fas fa-code
-        description: 强大的代码编辑器
-      - name: Postman
-        url: https://www.postman.com
-        icon: fas fa-paper-plane
-        description: API调试工具
-      - name: Git
-        url: https://git-scm.com
-        icon: fab fa-git-alt
-        description: 版本控制工具
-      - name: Docker
-        url: https://www.docker.com
-        icon: fab fa-docker
-        description: 容器化平台
-      - name: JetBrains
-        url: https://www.jetbrains.com
-        icon: fas fa-laptop-code
-        description: 专业开发IDE
-      - name: npm
-        url: https://www.npmjs.com
-        icon: fab fa-npm
-        description: Node.js包管理器
-      - name: Webpack
-        url: https://webpack.js.org
-        icon: fas fa-box-open
-        description: 前端打包工具
-      - name: GitHub Copilot
-        url: https://github.com/features/copilot
-        icon: fas fa-robot
-        description: AI编程助手
  - name: 设计资源
    icon: fas fa-palette
    sites:
@@ -124,18 +70,10 @@ categories:
        url: https://dribbble.com
        icon: fab fa-dribbble
        description: 设计师社区
-      - name: Behance
-        url: https://www.behance.net
-        icon: fab fa-behance
-        description: 创意设计平台
      - name: IconFont
        url: https://www.iconfont.cn
        icon: fas fa-icons
        description: 图标资源库
-      - name: Unsplash
-        url: https://unsplash.com
-        icon: fas fa-camera
-        description: 免费高质量图片
      - name: Adobe XD
        url: https://www.adobe.com/products/xd.html
        icon: fab fa-adobe
@@ -167,37 +105,13 @@ categories:
        url: https://carbon.now.sh
        icon: fas fa-code
        description: 代码图片生成器
-      - name: RegExr
-        url: https://regexr.com
-        icon: fas fa-search
-        description: 正则表达式测试
      - name: Excalidraw
        url: https://excalidraw.com
        icon: fas fa-pencil-alt
        description: 手绘风格图表工具
-      - name: Notion
-        url: https://www.notion.so
-        icon: fas fa-sticky-note
-        description: 多功能笔记工具
-      - name: Grammarly
-        url: https://www.grammarly.com
-        icon: fas fa-spell-check
-        description: 英文语法检查工具
  - name: 云服务平台
    icon: fas fa-cloud
    sites:
-      - name: AWS
-        url: https://aws.amazon.com
-        icon: fab fa-aws
-        description: 亚马逊云服务
-      - name: Azure
-        url: https://azure.microsoft.com
-        icon: fab fa-microsoft
-        description: 微软云平台
-      - name: Google Cloud
-        url: https://cloud.google.com
-        icon: fab fa-google
-        description: 谷歌云平台
      - name: Cloudflare
        url: https://www.cloudflare.com
        icon: fas fa-cloud
@@ -210,11 +124,15 @@ categories:
        url: https://www.netlify.com
        icon: fas fa-globe
        description: 静态网站托管
-      - name: DigitalOcean
-        url: https://www.digitalocean.com
-        icon: fab fa-digital-ocean
-        description: 简单云服务器
-      - name: Heroku
-        url: https://www.heroku.com
-        icon: fas fa-h-square
-        description: 应用部署平台
+      - name: AWS
+        url: https://aws.amazon.com
+        icon: fab fa-aws
+        description: 亚马逊云服务
+      - name: Azure
+        url: https://azure.microsoft.com
+        icon: fab fa-microsoft
+        description: 微软云平台
+      - name: Google Cloud
+        url: https://cloud.google.com
+        icon: fab fa-google
+        description: 谷歌云平台
--- a/config/_default/pages/friends.yml
+++ b/config/_default/pages/friends.yml
@@ -1,36 +0,0 @@
-# 默认页面配置（请勿直接修改）。
-# 建议复制到 config/user/pages/friends.yml 并按需调整。
-title: 友情链接           # 页面标题
-subtitle: 优秀的博主和朋友们 # 页面副标题
-
-# 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
-template: friends
-
-# 页面分类与站点列表
-categories:
-  - name: 技术博主
-    icon: fas fa-user-friends # 分类图标
-    sites:
-      - name: 小明的博客           # 站点名称
-        icon: fas fa-code         # 站点图标
-        description: 全栈开发工程师，分享技术心得 # 描述
-        url: "#"                  # 链接（示例）
-      - name: 小红的前端
-        icon: fas fa-paint-brush
-        description: 专注前端开发与设计
-        url: "#"
-      - name: 小张的后端
-        icon: fas fa-server
-        description: 分享后端开发经验
-        url: "#"
-  - name: 技术社区
-    icon: fas fa-laptop-code
-    sites:
-      - name: GitHub
-        icon: fab fa-github
-        description: 开源代码托管平台
-        url: https://github.com
-      - name: Stack Overflow
-        icon: fab fa-stack-overflow
-        description: 程序员问答社区
-        url: https://stackoverflow.com 
--- a/config/_default/pages/projects.yml
+++ b/config/_default/pages/projects.yml
@@ -1,36 +1,33 @@
 # 默认页面配置（请勿直接修改）。
 # 建议复制到 config/user/pages/projects.yml 并按需调整。
-title: 我的项目                 # 页面标题
-subtitle: 这里展示了我的一些个人项目和开源贡献  # 页面副标题
+title: 项目                 # 页面标题
+subtitle: 项目展示  # 页面副标题

 # 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
 template: projects

 # 页面分类与站点列表
+#
+# projects 模板采用“代码仓库风”卡片（repo 风格）。
+# 统计信息（language/stars/forks）为自动获取数据：
+# - 运行 `npm run sync-projects` 会联网抓取 GitHub 仓库信息，并写入 dev/ 缓存（仓库默认 gitignore）
+# - `npm run build` 默认不联网；缓存缺失时卡片仅展示标题与描述
 categories:
  - name: 个人项目
    icon: fas fa-code  # 分类图标（Font Awesome）
    sites:
-      - name: 个人导航站            # 站点名称
-        icon: fas fa-compass        # 手动图标（manual 模式显示；favicon 模式下作为回退）
-        description: 一个简洁美观的个人导航页面 # 站点描述
-        url: "#"                    # 链接（示例）
-      - name: Todo List
-        icon: fas fa-tasks
-        description: 基于Vue3的待办事项管理器
-        url: "#"
-      - name: 个人博客
-        icon: fas fa-blog
-        description: 使用Hexo搭建的技术博客
-        url: "#"
-  - name: 开源贡献
-    icon: fas fa-code-branch
+      - name: MeNav
+        icon: fab fa-github       # 手动图标（manual 模式显示；favicon 模式下作为回退）
+        description: 一键部署的个人导航站生成器，支持书签导入与自动构建，轻松整理展示您的网络收藏 # 站点描述
+        url: https://github.com/rbetree/menav
+      - name: MarksVault
+        icon: fab fa-github
+        description: 一个强大的浏览器扩展，用于智能管理、整理和安全备份您的书签数据
+        url: "https://github.com/rbetree/MarksVault"
+  - name: star
+    icon: fas fa-star
    sites:
-      - name: Project A
+      - name: CLIProxyAPI
        icon: fab fa-github
-        description: 开源项目贡献
-        url: "#"
-      - name: Project B
-        icon: fab fa-github
-        description: 开源项目贡献
-        url: "#" 
+        description: Wrap Gemini CLI, Antigravity, ChatGPT Codex, Claude Code, Qwen Code, iFlow as an OpenAI/Gemini/Claude/Codex compatible API service, allowing you to enjoy the free Gemini 2.5 Pro, GPT 5, Claude, Qwen model through API
+        url: "https://github.com/router-for-me/CLIProxyAPI"
--- a/config/_default/site.yml
+++ b/config/_default/site.yml
@@ -32,9 +32,37 @@ fonts:
    
 # 个人资料：显示在首页顶部的欢迎信息
 profile:
+  # 注意：首页（导航第一项）标题区优先使用 profile.title/profile.subtitle
+  # 因此建议把首页希望展示的文案写在这里，避免“改了 pages/<首页id>.yml 但首页不生效”的误会
  title: Hello,
  subtitle: Welcome to My Navigation

+# RSS（Phase 2）：用于 articles 页面文章聚合
+# 说明：
+# - `npm run build` 默认不联网；仅 `npm run sync-articles` 会联网抓取并写入缓存
+# - 缓存目录建议放在 dev/（仓库默认 gitignore），避免误提交
+rss:
+  enabled: true
+  cacheDir: dev
+  fetch:
+    timeoutMs: 10000       # 单请求超时（毫秒）
+    totalTimeoutMs: 60000  # 全流程总超时（毫秒）
+    concurrency: 5         # 并发抓取站点数
+    maxRetries: 1          # 单站点重试次数（best-effort）
+    maxRedirects: 3        # 最大重定向次数
+  articles:
+    perSite: 8             # 单站点最多抓取条数
+    total: 50              # 全站聚合上限
+    summaryMaxLength: 200  # 摘要最大长度（字符）
+
+# GitHub：用于 projects 页面右侧“贡献热力图”（可选）
+# - username：你的 GitHub 用户名（例如 torvalds）
+# - heatmapColor：热力图主题色（不带 #，例如 339af0）
+github:
+  username: "rbetree"      # 你的 GitHub 用户名（例如 torvalds；为空则 projects 页不展示热力图）
+  heatmapColor: 339af0
+  cacheDir: dev     # projects 仓库元信息缓存目录（默认 dev，仓库默认 gitignore）
+
 # 社交媒体链接：显示在侧边栏底部；可按需增删
 social:
  - name: GitHub
@@ -54,16 +82,13 @@ social:
 navigation:
  - name: 常用        # 菜单名称
    icon: fas fa-star  # Font Awesome 图标类
-    id: home           # 页面标识符（唯一，需与 pages/<id>.yml 对应）
+    id: common          # 页面标识符（唯一，需与 pages/<id>.yml 对应）
  - name: 项目
    icon: fas fa-project-diagram
    id: projects
  - name: 文章
    icon: fas fa-book
    id: articles
-  - name: 朋友
-    icon: fas fa-users
-    id: friends
  - name: 书签
    icon: fas fa-bookmark
    id: bookmarks
--- a/config/update-instructions.md
+++ b/config/update-instructions.md
@@ -0,0 +1,59 @@
+# 更新说明（兼容性移除 / 迁移指南）
+
+本文档说明本次“页面模板差异化改进”阶段，在配置/构建链路上**移除的历史兼容行为**以及如何迁移。
+
+最后更新：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/` 补齐缺失项。
+