diff --git a/README.md b/README.md index 82d687e..f5a0664 100644 --- a/README.md +++ b/README.md @@ -41,14 +41,13 @@ - [近期更新](#近期更新) - [技术栈](#技术栈) - [项目结构](#项目结构) +- [文档导航](#文档导航) - [快速开始](#快速开始) - [部署方式](#部署方式) - [部署到GitHub Pages](#快速部署到github-pages) - [部署到自己的服务器](#部署到服务器) - [其他CI/CD服务部署](#其他cicd托管选项) - [配置指南](#设置配置文件) - - [使用配置](#使用配置) - - [配置详解](#配置详解) - [书签导入](#书签导入功能) - [常见问题](#常见问题) - [Star-History](#Star-History) @@ -238,6 +237,15 @@ menav/ │ └── pages/ # 用户页面配置 ``` +## 文档导航 + +- 配置系统（完全替换策略、目录结构、示例）：[`config/README.md`](config/README.md) +- 书签导入（格式要求、流程、常见问题）：[`bookmarks/README.md`](bookmarks/README.md) +- 模板系统（组件、回退、数据流）：[`templates/README.md`](templates/README.md) +- 源码结构（各脚本职责）：[`src/README.md`](src/README.md) +- Handlebars helpers（模板辅助函数）：[`src/helpers/README.md`](src/helpers/README.md) +- 静态资源（样式/图片等）：[`assets/README.md`](assets/README.md) + ## 快速开始
@@ -257,7 +265,7 @@ cd menav npm install ``` -3. 完成配置（见[设置配置文件](##设置配置文件)） +3. 完成配置（见[设置配置文件](#设置配置文件)） 4. 导入书签（可选） - 将浏览器导出的HTML格式书签文件放入`bookmarks`目录 @@ -326,7 +334,7 @@ npm run format 创建个人配置文件: - **重要:** 始终创建自己的用户配置文件，不要直接修改默认配置文件 -- 完成配置文件（见[设置配置文件](##设置配置文件)） +- 完成配置文件（见[设置配置文件](#设置配置文件)） - 提交您的配置文件到仓库 #### 第三步：等待自动部署 @@ -415,7 +423,9 @@ server { ## 设置配置文件 -MeNav使用模块化配置方式，将配置分散到多个文件中，更易于管理和维护。 +MeNav 使用模块化配置方式，将配置分散到多个 YAML 文件中，更易于管理和维护。 + +完整说明请直接看：[`config/README.md`](config/README.md)（以该文档为准）。 > **🔔 重要提示：** 请务必在`config/user/`目录下创建并使用您自己的配置文件，不要直接修改默认配置文件，以便后续更新项目时不会丢失您的个性化设置。 @@ -425,363 +435,22 @@ MeNav使用模块化配置方式，将配置分散到多个文件中，更易于 **注意：** 采用完全替换策略，而非合并。系统会选择存在的用户配置，完全忽略默认配置。 -### 使用配置 +### 最小可用配置（快速指引） -* **创建配置目录**: - - 在`config/user/`目录下创建您的自定义配置文件 - - 可以参考项目结构中的`config/_default/`目录结构 - - 至少需要创建`site.yml`（缺失时构建会直接报错退出，避免生成空白站点） - - 首次使用建议先完整复制 `config/_default/` 到 `config/user/`，再按需修改（因为配置采用“完全替换”策略，不会从默认配置补齐缺失项） - -### 配置详解 - -
-点击展开 - -MeNav的配置系统分为两个主要部分，对应两种不同类型的配置文件： - -1. `site.yml` - 网站基本信息、字体、个人资料、社交媒体链接和导航菜单配置 -2. `pages/` 目录 - 各页面的内容配置 - -以下详细介绍每个配置文件的结构和用途。 - -### 一、site.yml 配置文件 - -site.yml文件包含网站的基本信息、字体设置、个人资料、社交媒体链接和导航菜单等全局配置，这些设置会影响整个网站的呈现。 - -```yaml -# 网站基本信息 -title: "我的导航站" # 网站标题，显示在浏览器标签和页面顶部 -description: "个人网址导航" # 网站描述，用于SEO和分享卡片 -author: "张三" # 作者姓名 -favicon: "menav.svg" # 网站图标，支持ico、png等格式 -logo_text: "导航站" # 左上角显示的Logo文本 - -icons: - mode: favicon # 可选: favicon | manual（默认 favicon） - -# 字体设置 -fonts: - title: # 标题字体设置 - family: "Roboto" # 字体名称 - weight: 700 # 字重值：400常规、500中等、700粗体 - source: "google" # 字体来源：google或system - subtitle: # 副标题字体 - family: "Noto Sans SC" - weight: 500 - source: "google" - body: # 正文字体 - family: "Noto Sans SC" - weight: 400 - source: "google" - -# 个人资料配置 -profile: - title: "欢迎来到我的导航站" # 主标题/欢迎语 - subtitle: "收集实用网站和工具" # 副标题 - description: "这里整理了我日常使用的网站和工具，方便快速访问。" # 详细描述 - -# 社交媒体链接 -social: - - name: "GitHub" - url: "https://github.com/your-username" - icon: "fab fa-github" - - name: "Twitter" - url: "https://twitter.com/your-username" - icon: "fab fa-twitter" - # 更多社交媒体... -``` - -#### 网站图标模式（icons.mode） - -支持两种站点卡片图标模式，默认使用 favicon API： - -- mode=favicon：使用 Google Favicon API 加载站点图标；加载失败时回退为 Font Awesome 的 `fas fa-link`；图标图片使用 `loading="lazy"` 延迟加载以提升首页性能。 -- mode=manual：沿用手动指定的 Font Awesome 图标，不发起任何 favicon 请求。 - -所用 Favicon API： -`https://t3.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url={{url}}&size=32` - -隐私说明： -- 启用 `mode=favicon` 时，页面会请求第三方服务以获取图片，可能将站点 `URL` 发送至该服务商（Google）。 - - -```yaml -# 导航配置 -navigation: - - name: "首页" # 菜单项名称 - icon: "fas fa-home" # 菜单项图标 - id: "home" # 页面标识符（必须唯一） - active: true # 是否默认激活（只能有一个为true） - - name: "项目" - icon: "fas fa-project-diagram" - id: "projects" - - name: "文章" - icon: "fas fa-book" - id: "articles" - # 更多导航项... -``` - -> **📝 温馨提示**： -> - 关于**字体设置**： -> - **system**表示使用系统自带字体，无需额外加载，页面加载速度更快 -> - **google**表示从Google Fonts加载字体，选择更丰富，但可能影响加载速度 -> - 中文网站推荐使用"Noto Sans SC"、"Source Han Sans CN"等支持中文的字体 -> - 设置字重时请确保所选字体支持该字重值，否则可能无法正确显示 -> - 关于**个人资料**：profile.description支持较长文本，可以添加一些个性化的介绍或使用说明，让您的导航站更具特色 -> - 关于**社交媒体链接**：这些链接会显示在网站侧边栏的底部 -> - 关于**导航配置**： -> - 每个导航项的`id`必须唯一，并且有对应的页面配置文件（该id必须与`pages/`文件夹中的页面配置文件名一致） -> - 只能设置一个导航项的`active`为`true`，作为默认显示页面 -> - 图标使用Font Awesome 5图标库，格式为`前缀 fa-图标名` -> - 导航菜单的顺序与此配置中的顺序一致，可以通过调整项目顺序来更改导航顺序 - -### 二、pages目录 配置文件 - -pages目录包含每个页面的详细配置，每个文件对应一个页面。文件名必须与 `site.yml` 中 `navigation` 配置的 `id` 一致。 - -例如，对于导航中的"home"页面，需要创建`config/user/pages/home.yml`： - -```yaml -# pages/home.yml示例 -title: "我的主页" # 页面标题 -subtitle: "常用网站导航" # 页面副标题 - -# 分类和网站配置 -categories: - - name: "常用工具" # 分类名称 - icon: "fas fa-tools" # 分类图标 - sites: # 该分类下的网站列表 - - name: "GitHub" # 网站名称 - url: "https://github.com" # 网站链接 - icon: "fab fa-github" # 网站图标 - description: "全球最大的代码托管平台" # 网站描述 - - name: "Google" - url: "https://google.com" - icon: "fab fa-google" - description: "全球最大的搜索引擎" - # 更多网站... - # 更多分类... -``` - -自定义页面配置示例（以"notes"为例）： - -1. 首先在`site.yml`的`navigation`部分添加对应的导航项： -```yaml -# config/user/site.yml -navigation: - - name: "笔记" - icon: "fas fa-sticky-note" - id: "notes" - active: false -``` - -2. 然后创建`config/user/pages/notes.yml`配置文件： -```yaml -title: "我的笔记收藏" # 页面标题 -subtitle: "学习和工作笔记资源" # 页面副标题 -categories: # 该页面的分类和网站 - - name: "编程笔记" - icon: "fas fa-code" - sites: - - name: "Python学习笔记" - url: "https://example.com/python-notes" - icon: "fab fa-python" - description: "Python编程技巧和案例" - # 更多网站... -``` -#### 多层级嵌套配置 - -MeNav 支持多层级嵌套配置，允许创建更复杂的内容组织结构。特别适用于书签页面，可以创建分类 -> 子分类 -> 分组 -> 网站的多层结构。 - -##### 配置结构说明 - -多层级嵌套配置支持以下层级结构： - -1. **二层级结构**（默认）： - ``` - 分类 (categories) - └── 网站 (sites) - ``` - -2. **三层级结构**： - ``` - 分类 (categories) - └── 分组 (groups) - └── 网站 (sites) - ``` - -3. **四层级结构**： - ``` - 分类 (categories) - └── 子分类 (subcategories) - └── 分组 (groups) - └── 网站 (sites) - ``` - -##### 四层级结构示例 - -```yaml -categories: - - name: "技术资源" - icon: "fas fa-laptop-code" - subcategories: - - name: "前端开发" - icon: "fas fa-code" - groups: - - name: "框架库" - icon: "fas fa-cube" - sites: - - name: "React" - url: "https://reactjs.org/" - icon: "fab fa-react" - description: "React官方文档" - - name: "Vue.js" - url: "https://vuejs.org/" - icon: "fab fa-vuejs" - description: "Vue.js官方文档" - - name: "状态管理" - icon: "fas fa-database" - sites: - - name: "Redux" - url: "https://redux.js.org/" - icon: "fas fa-database" - description: "Redux状态管理" - - name: "Vuex" - url: "https://vuex.vuejs.org/" - icon: "fas fa-database" - description: "Vue状态管理" - - name: "后端开发" - icon: "fas fa-server" - groups: - - name: "Node.js生态" - icon: "fab fa-node-js" - sites: - - name: "Express" - url: "https://expressjs.com/" - icon: "fas fa-server" - description: "Node.js Web框架" - - name: "Koa" - url: "https://koajs.com/" - icon: "fas fa-leaf" - description: "下一代Node.js框架" -``` - -### 向后兼容性 - -多层级嵌套配置完全向后兼容： - -- 现有的二层级结构（categories -> sites）配置无需修改即可继续使用 -- 系统会自动检测配置结构并应用相应的模板和样式 -- 可以在同一配置中混合使用不同层级结构（某些分类使用二级结构，某些使用三级或四级结构） -- 模板系统会自动处理不同层级结构，无需手动指定模板类型 - - -> **📝提示**： -> - 每个页面可以拥有不同的分类和网站 -> - 网站描述建议简洁明了，不超过30个字符，以确保显示美观 -> - 不同页面可以特化用于不同用途，如"工作"、"学习"、"娱乐"等 -> - 页面数量不限，但建议控制在合理范围内，避免导航过长 - -### 三、配置文件结构示例 - -**完整配置结构**： - -``` -config/user/ -├── site.yml # 网站基本信息、字体、个人资料、社交媒体链接和导航菜单配置 -└── pages/ - ├── home.yml # 首页配置 - ├── projects.yml # 项目页配置 - ├── articles.yml # 文章页配置 - ├── friends.yml # 朋友页配置 - └── notes.yml # 自定义笔记页配置 -``` - -> **📝 首次设置建议**： -> - 首先复制`config/_default/`目录中的文件到`config/user/`目录 -> - 然后逐步修改各配置文件，保持目录结构一致 -> - 使用文本编辑器时注意保持正确的YAML格式和缩进 - -
+- 首次使用建议先完整复制 `config/_default/` 到 `config/user/`，再按需修改（因为配置采用“完全替换”策略，不会从默认配置补齐缺失项）。 +- 至少需要有 `config/user/site.yml`（缺失时构建会直接报错退出，避免生成空白站点）。 ## 书签导入功能 -MeNav支持从浏览器导入书签，快速批量添加网站链接，无需手动录入。 +MeNav 支持从浏览器导入书签，快速批量添加网站链接；也支持与 MarksVault 扩展集成自动同步。 -### MarksVault 浏览器扩展集成 - -[MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展提供与 MeNav 的无缝集成： - -- **一键推送书签**：通过扩展直接将书签推送到您的 MeNav 项目 -- **自动化处理**：推送的书签文件会被自动处理并转换为配置 -- **自动删除**：处理完成后，原始书签文件会被自动删除，以防止重复处理 - -### 配置加载优先级 - -书签配置按以下优先级加载（从高到低）： - -1. `config/user/pages/bookmarks.yml` （用户配置） -2. `config/_default/pages/bookmarks.yml` （默认配置） - -**注意：** 书签配置采用完全替换策略，系统只会使用找到的最高优先级配置。 - -### 导入步骤详解 - -#### 使用 MarksVault 浏览器扩展（推荐） - - - 安装 [MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展 - - 在浏览器中登录并授权 - - 使用扩展任务页中新建任务，将书签推送到您的 MeNav 项目 - - 系统将自动处理并部署更新后的导航站 - -#### 手动导入 -
-点击展开 - -1. **从浏览器导出html书签** - -2. **导入书签到MeNav** - - **GitHub Pages方式**: - - Fork本仓库后，在您的仓库中创建`bookmarks`目录 - - 上传HTML格式书签文件到此目录 - - GitHub Actions会自动处理文件并生成配置 - - **本地开发方式**: - - 在项目根目录创建`bookmarks`文件夹 - - 复制HTML书签文件到此文件夹 - - 运行`npm run import-bookmarks`命令处理书签文件 - - 系统生成配置文件后即可使用`npm run dev`预览 - -#### 根路径书签处理 - -如果HTML书签文件中存在`不在任何文件夹内`的根路径书签，系统会： -- 自动创建名为"根目录书签"的特殊分类 -- 该分类始终位于所有其他分类之前（第一位） -- 只有存在根路径书签时才会创建该分类 - -
- -> 💡 *版本管理建议*：若你希望每次导入书签生成的 `bookmarks.yml` 内容保持确定性（避免因时间戳导致的无意义 diff），可在运行导入时设置环境变量：`MENAV_BOOKMARKS_DETERMINISTIC=1`。 - -> 生成的配置可在`config/user/pages/bookmarks.yml`中查看和编辑 +完整说明请直接看：[`bookmarks/README.md`](bookmarks/README.md)（以该文档为准）。 ## 常见问题
如何自定义Handlebars模板？ -MeNav现在使用Handlebars模板系统，您可以通过以下步骤自定义模板： - -1. **基本修改**：Fork项目后，您可以编辑`templates`目录下的模板文件 -2. **结构说明**： - - `layouts`：包含整体页面布局模板 - - `pages`：包含各页面的主要内容模板 - - `components`：包含可复用的组件模板 -3. **组件扩展**：创建新的组件模板时，需要在generator.js中注册，才能通过`{{> component-name}}`语法使用 -4. **自定义页面**：新增页面需要在`templates/pages`添加模板，并确保有对应的配置文件 - -修改模板后，需要重新构建项目以应用更改。 +模板系统完整说明请见：[`templates/README.md`](templates/README.md)。
diff --git a/bookmarks/README.md b/bookmarks/README.md index a863b9d..87bf6e6 100644 --- a/bookmarks/README.md +++ b/bookmarks/README.md @@ -3,8 +3,11 @@ ## 目录 - [目录概述](#目录概述) -- [功能说明](#功能说明) +- [书签导入功能](#书签导入功能) +- [配置加载优先级（完全替换）](#配置加载优先级完全替换) +- [MarksVault 扩展集成](#marksvault-扩展集成) - [书签导入流程](#书签导入流程) +- [确定性输出](#确定性输出) - [支持的浏览器](#支持的浏览器) - [书签格式要求](#书签格式要求) - [文件处理机制](#文件处理机制) @@ -13,7 +16,7 @@ `bookmarks` 目录是 MeNav 项目中用于存放浏览器导出的书签文件的专用目录。该目录与书签导入功能直接关联，用于自动将浏览器书签转换为 MeNav 配置文件，从而快速生成个人导航站点。 -## 功能说明 +## 书签导入功能 书签导入功能允许用户： @@ -24,6 +27,23 @@ 这一功能极大简化了网站内容的初始设置过程，特别适合需要迁移大量书签的用户。 +## 配置加载优先级（完全替换） + +书签页配置遵循项目的“完全替换”策略：系统只会使用找到的最高优先级配置，不会把默认配置与用户配置合并。 + +优先级（高 → 低）： + +1. `config/user/pages/bookmarks.yml`（用户配置，通常由导入脚本生成） +2. `config/_default/pages/bookmarks.yml`（默认配置） + +## MarksVault 扩展集成 + +[MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展可与 MeNav 集成，实现书签自动同步： + +- **一键推送书签**：扩展将书签 HTML 文件推送到仓库的 `bookmarks/` 目录 +- **自动化处理**：GitHub Actions 检测到书签文件后自动运行导入脚本生成配置 +- **自动清理**：处理完成后会删除已导入的 HTML 文件，避免重复处理 + ## 书签导入流程 完整的书签导入流程如下： @@ -34,6 +54,10 @@ ```bash npm run import-bookmarks ``` + （可选）若希望生成结果保持确定性（便于版本管理，减少时间戳导致的无意义 diff）： + ```bash + MENAV_BOOKMARKS_DETERMINISTIC=1 npm run import-bookmarks + ``` 4. 系统自动解析书签文件内容 5. 根据书签文件夹结构生成分类 6. 生成配置文件保存到 `config/user/pages/bookmarks.yml` @@ -44,6 +68,16 @@ > **重要说明**：在本地开发中，`npm run dev` 命令**不会**自动处理书签文件。您必须先手动运行 `npm run import-bookmarks` 命令处理书签，然后再运行 `npm run dev` 查看效果。这与 GitHub Actions 中的自动处理流程不同，请务必注意。 +## 确定性输出 + +默认情况下，导入脚本会在生成的 `bookmarks.yml` 顶部写入时间戳注释，导致每次导入都会产生 diff。 + +若你希望生成结果尽量稳定（只有书签内容变化才产生 diff），可使用环境变量开启确定性输出： + +```bash +MENAV_BOOKMARKS_DETERMINISTIC=1 npm run import-bookmarks +``` + ## 支持的浏览器 MeNav 书签导入功能支持从以下浏览器导出的书签文件： @@ -89,10 +123,11 @@ MeNav 书签导入功能支持从以下浏览器导出的书签文件： 4. **图标分配**： - 根据URL自动匹配合适的 Font Awesome 图标 - 为每个链接和分类分配图标 + - 当 `icons.mode: favicon` 时，页面通常会优先显示站点 favicon；配置里的 `icon` 主要用于回退显示或在 `icons.mode: manual` 时使用（详见 `config/README.md`） 5. **配置生成**： - 创建符合 MeNav 配置格式的 YAML 文件 - 按层级组织分类和链接 - 应用自动生成的元数据 -将书签放入此目录后，您可以立即利用 MeNav 的书签处理功能，快速将书签转化为个性化导航站点。 \ No newline at end of file +将书签放入此目录后，您可以立即利用 MeNav 的书签处理功能，快速将书签转化为个性化导航站点。 diff --git a/config/README.md b/config/README.md index 1295416..d65b807 100644 --- a/config/README.md +++ b/config/README.md @@ -5,9 +5,14 @@ - [目录概述](#目录概述) - [配置目录结构](#配置目录结构) - [配置加载机制](#配置加载机制) +- [推荐用法](#推荐用法) - [模块化配置文件](#模块化配置文件) - [网站基础配置](#网站基础配置) - [页面配置](#页面配置) +- [配置详解](#配置详解) + - [site.yml 常用字段](#siteyml-常用字段) + - [pages/ 页面配置](#pages-页面配置) + - [多层级嵌套配置（2-4层）](#多层级嵌套配置2-4层) - [配置优先级](#配置优先级) - [配置示例](#配置示例) - [最佳实践](#最佳实践) @@ -46,6 +51,16 @@ MeNav 配置系统采用“完全替换”策略（不合并），按以下优 也就是说：`config/user/` 一旦存在，就需要包含一套完整的配置（例如 `site.yml` 与必要的 `pages/*.yml`），系统不会把缺失部分从默认配置补齐。 +## 推荐用法 + +为避免文档与配置字段长期不同步，建议按以下方式使用与维护： + +1. **首次使用**：完整复制 `config/_default/` 到 `config/user/`，再按需修改。 +2. **字段与结构的权威参考**： + - 全局配置：[`_default/site.yml`](_default/site.yml) + - 页面配置：[`_default/pages/`](_default/pages/) +3. **多层级嵌套书签示例**：[`_default/pages/bookmarks-four-level.yml`](_default/pages/bookmarks-four-level.yml)（2~4 层结构均有覆盖） + ## 模块化配置文件 ### 网站基础配置 @@ -72,6 +87,76 @@ MeNav 配置系统采用“完全替换”策略（不合并），按以下优 - `bookmarks.yml`: 书签页面配置 - 自定义页面配置 +## 配置详解 + +本章节用于补齐“怎么配才是对的”这类细节说明。为了避免示例长期过时，字段与结构的权威参考始终以默认配置为准： + +- 全局配置：[`_default/site.yml`](_default/site.yml) +- 页面配置：[`_default/pages/`](_default/pages/) + +### site.yml 常用字段 + +`site.yml` 中字段较多，以下是常用项的解释与注意点（完整字段请以默认配置为准）： + +1. **基础信息** + - `title`：站点标题 + - `description`：站点描述（SEO/分享） + - `author`：作者/署名 + - `favicon`、`logo_text`：站点图标与左上角 Logo 文本 + +2. **图标模式（隐私相关）** + - `icons.mode: favicon | manual` + - `favicon`：会请求第三方服务（Google）获取站点 favicon，失败自动回退到 Font Awesome 图标 + - `manual`：完全使用手动 Font Awesome 图标，不发起外部请求（适合内网/离线/隐私敏感场景） + +3. **字体** + - `fonts.*.source: google | system` + - `system`：使用系统字体，加载更快；`google`：可选字体更多但可能受网络影响 + - 中文站点建议选择支持中文与字重的字体（如 `Noto Sans SC`）；请确保所选字体包含配置的字重，否则可能显示异常 + +4. **顶部欢迎信息与社交链接** + - `profile`：首页顶部欢迎信息 + - `social`：侧边栏底部社交链接 + - `profile.description` 可写较长文本，用于放置个性化介绍或使用说明 + +5. **导航** + - `navigation[]`：页面入口列表，`id` 需唯一，并与 `pages/` 中配置文件名对应（例如 `id: home` 对应 `pages/home.yml`） + - 只允许一个导航项 `active: true` 作为默认页 + - 图标使用 Font Awesome 类名字符串（例如 `fas fa-home`、`fab fa-github`） + - 导航显示顺序与数组顺序一致，可通过调整数组顺序改变导航顺序 + +### pages/ 页面配置 + +页面配置位于 `pages/*.yml`，每个文件对应一个页面内容，文件名与导航 `id` 对应： + +- `pages/home.yml`：首页（通常是 `categories -> sites`） +- `pages/projects.yml` / `articles.yml` / `friends.yml`：示例页面（可按需删改） +- `pages/bookmarks.yml`：书签页（通常由导入脚本生成，也可以手动维护） + +> 提示：自定义页面时，先在 `site.yml` 的 `navigation` 中增加一个 `id`，再创建同名的 `pages/.yml`。 +> +> 站点描述建议简洁（例如不超过 30 个字符），以保证卡片展示更美观。 + +### 多层级嵌套配置（2-4层） + +书签与分类支持 2~4 层嵌套，用于更好组织大量站点。建议直接参考默认示例： + +- 四层结构示例：[`_default/pages/bookmarks-four-level.yml`](_default/pages/bookmarks-four-level.yml) + +层级命名约定（自顶向下）： + +1. `categories`：顶层分类 +2. `subcategories`：子分类 +3. `groups`：分组 +4. `subgroups`：子分组 +5. `sites`：站点（叶子节点） + +#### 向后兼容性 + +- 原有二层结构（`categories -> sites`）无需修改即可继续使用 +- 系统会自动识别层级结构并匹配对应的模板/样式 +- 允许在同一份配置中混用不同层级（例如某些分类是二层，某些分类是三/四层） + ## 配置优先级 配置项的优先级从高到低为： @@ -172,6 +257,6 @@ categories: - 定期备份您的用户配置 4. **配置验证**: - - 修改配置后先在本地构建测试 - - 使用 `npm run dev` 预览更改效果 - - 确保 YAML 语法正确无误 + - 修改配置后运行 `npm run check`（语法检查 + 单测 + 构建） + - 需要本地预览时运行 `npm run dev`（命令入口见 [`../README.md#快速开始`](../README.md#快速开始)） + - 确保 YAML 语法正确无误 diff --git a/templates/README.md b/templates/README.md index 853a5a1..a69ff85 100644 --- a/templates/README.md +++ b/templates/README.md @@ -299,7 +299,9 @@ categories: {{/if}} ``` -提示：关于 `icons.mode` 与隐私说明，请参见 README 的“网站图标模式（icons.mode）”章节与“近期更新”。 +提示：关于 `icons.mode` 的配置与隐私说明，请参见： +- `config/README.md` 的 `site.yml 常用字段`：[`../config/README.md#siteyml-常用字段`](../config/README.md#siteyml-%E5%B8%B8%E7%94%A8%E5%AD%97%E6%AE%B5) +- 根目录 `README.md` 的“近期更新”：[`../README.md#近期更新`](../README.md#%E8%BF%91%E6%9C%9F%E6%9B%B4%E6%96%B0) ## 模板数据流