menav/config/update-instructions-20260102.md

更新说明（2026-01-02）

本文档用于说明 Issue #30（外部资源/图标/嵌套交互）相关改动中，配置层面的新增字段、行为变更与迁移要点。

关联 Issue：https://github.com/rbetree/menav/issues/30

最后更新：2026-01-02

---

1. 新增/扩展的配置字段

1.1 site.yml -> icons.mode（站点卡片图标模式 / 隐私）

用途：控制“站点卡片图标”的全局渲染方式。

取值：

• favicon：根据站点 URL 通过第三方服务加载站点 favicon（失败时回退到 Font Awesome 图标）
• manual：始终使用配置中的 Font Awesome 图标类名（不发起 favicon 外部请求）

注意：

• 该配置位于 site.yml 的 icons: 节点下（默认示例见 config/_default/site.yml）。
• 配置目录采用“完全替换”策略：若启用 config/user/，需要在 config/user/site.yml 中设置该字段才会生效。
• 切换后需要重新生成页面（npm run build / npm run dev）才能影响生成的 HTML。

示例：

# config/user/site.yml
icons:
  mode: manual

---

1.2 pages/*.yml -> sites[].faviconUrl（站点级自定义图标链接）

用途：为单个站点指定图标链接（可远程或本地相对路径），用于兜底“favicon 服务返回默认图标/网络不可达”等情况。

说明：

• faviconUrl 优先级最高：一旦设置，将直接使用该图片链接渲染图标。
• 本地路径建议以 assets/ 开头；构建时会复制到 dist/ 同路径，便于离线/内网使用。

示例：

sites:
  - name: '内部系统'
    url: 'https://intranet.example/'
    faviconUrl: 'assets/icons/intranet.png'

---

1.3 pages/*.yml -> sites[].forceIconMode（站点级强制图标模式）

用途：强制该站点使用指定模式（不设置则跟随全局 icons.mode）。

取值：

• favicon：强制走 favicon（外部请求）
• manual：强制走手动图标（不发起 favicon 外部请求）

优先级：

• faviconUrl > forceIconMode > 全局 icons.mode

示例：

sites:
  - name: 'Ant Design'
    url: 'https://ant.design/'
    icon: 'fas fa-th'
    forceIconMode: manual

---

2. 行为变更与修复要点（无需迁移字段）

2.1 icons.mode 全局切换修复

修复点：此前 site.yml 中的 icons 没有被提升为顶层 icons，导致模板与运行时读取到的仍是默认 favicon。本次已修复，site.yml -> icons.mode 会被模板/运行时统一读取生效。

2.2 favicon 双域名回退（.com → .cn）

修复点：favicon 默认使用 t3.gstatic.com，失败时自动切换 t3.gstatic.cn 重试一次，提升国内网络可用性。

2.3 多级结构站点新标签页打开一致性

修复点：多级结构（subcategories/groups/subgroups）下站点默认值未递归补齐，导致 external 为 undefined 时不输出 target="_blank"。本次已在生成阶段递归补齐 sites[].external 默认 true（显式 external: false 保持同页打开）。

---

3. 迁移建议（从旧版本升级）

1. 若使用 config/user/：请在 config/user/site.yml 中设置 icons.mode，然后执行 npm run build 重新生成页面。
2. 若遇到某些站点 favicon 始终显示默认图标：建议对该站点配置 forceIconMode: manual（使用 Font Awesome）或提供 faviconUrl 指向可靠图片（远程或本地 assets/）。