From da1e3fedd6650fd8a173c5aca8ca1625e8af47e1 Mon Sep 17 00:00:00 2001 From: coolzr Date: Fri, 24 Oct 2025 01:28:37 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 112 ++++++++++++++++++++++++++++-------- src/README.md | 3 - templates/README.md | 137 +++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 223 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 0125432..8bc1a5f 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,7 @@ - 👥 支持展示社交媒体链接 - 📝 支持多个内容页面 - 📌 支持从浏览器导入书签 +- 📚 支持2-4层级的多层级嵌套书签结构，更好地组织内容 - 🔄 与 [MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展集成，支持自动推送书签 - 🧩 模块化配置 - 🔄 可部署到GitHub Pages或任何类似的CI/CD服务，及任何服务器 @@ -145,7 +146,6 @@ icons: **1. 移除双文件配置支持** - ✅ 完全移除了对双文件配置方法的支持 - ✅ 简化了配置加载逻辑，现在仅支持模块化配置 -- ✅ 保留配置迁移工具 ### 2025/05/03 @@ -209,7 +209,6 @@ menav/ ├── src/ # 源代码 │ ├── generator.js # 静态网站生成器 │ ├── bookmark-processor.js # 书签导入处理器 -│ ├── migrate-config.js # 配置迁移工具 │ └── script.js # 前端JavaScript脚本 ├── templates/ # Handlebars模板目录 │ ├── layouts/ # 布局模板 @@ -597,6 +596,92 @@ categories: # 该页面的分类和网站 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）配置无需修改即可继续使用 +- 系统会自动检测配置结构并应用相应的模板和样式 +- 可以在同一配置中混合使用不同层级结构（某些分类使用二级结构，某些使用三级或四级结构） +- 模板系统会自动处理不同层级结构，无需手动指定模板类型 + > **📝提示**： > - 每个页面可以拥有不同的分类和网站 @@ -799,29 +884,6 @@ icons: 提示：更改配置后重新构建即可生效。 -
-如何从旧式配置迁移到模块化配置？ - -由于MeNav已经移除了对旧式配置文件的支持，如果您仍在使用旧式配置文件，必须使用迁移工具进行转换： - -1. 自动迁移方式： - ```bash - npm run migrate-config - ``` - 该命令会自动检测旧式配置文件，并将其全部转换为模块化配置格式。 - -2. 迁移过程： - - 工具会识别`config.yml`、`config.user.yml`、`bookmarks.yml`和`bookmarks.user.yml` - - 将它们转换并拆分到`config/user/`目录的对应文件中 - - 保留所有原始配置数据，不会丢失任何设置 - -3. 迁移后： - - 所有配置将被放置在`config/user/`目录及其子目录 - - 迁移工具会告诉您可以安全删除的旧式配置文件 - - 新的模块化配置立即生效，无需额外设置 - -**重要提示**：MeNav现在只支持模块化配置文件。如果您仍在使用旧式配置，必须使用迁移工具进行转换才能继续使用最新版本的MeNav。 -
如何使用MarksVault扩展自动同步书签？ diff --git a/src/README.md b/src/README.md index 15e840e..c72f4ba 100644 --- a/src/README.md +++ b/src/README.md @@ -40,9 +40,6 @@ - 转换浏览器书签为MeNav配置格式 - 提供书签导入功能 -- **migrate-config.js**: 配置迁移工具 - - 处理配置文件格式升级 - - 确保向后兼容性 ### helpers 目录函数（辅助功能） diff --git a/templates/README.md b/templates/README.md index 1a2b775..bd6ea8c 100644 --- a/templates/README.md +++ b/templates/README.md @@ -8,6 +8,7 @@ - [布局模板](#布局模板) - [页面模板](#页面模板) - [组件模板](#组件模板) + - [多层级嵌套模板组件](#多层级嵌套模板组件) - [模板数据流](#模板数据流) - [模板使用示例](#模板使用示例) - [最佳实践](#最佳实践) @@ -113,7 +114,8 @@ templates/ **主要组件**: - `navigation.hbs` - 导航菜单 - `site-card.hbs` - 站点卡片 -- `category.hbs` - 分类容器 +- `category.hbs` - 分类容器（支持多层级嵌套） +- `group.hbs` - 分组容器（支持多层级嵌套） - `social-links.hbs` - 社交链接 - `search-results.hbs` - 搜索结果展示 @@ -128,6 +130,139 @@ templates/ {{/if}} ``` +### 多层级嵌套模板组件 + +#### category.hbs - 分类容器组件 + +`category.hbs` 是支持多层级嵌套的核心组件，可以递归渲染分类和子分类结构。 + +**功能特性**: +- 支持无限层级的分类嵌套 +- 自动计算标题层级（h2, h3, h4...） +- 根据层级自动应用对应的CSS类 +- 支持三种内容类型：子分类、分组、站点 + +**递归渲染原理**: +通过在模板内部调用自身实现递归渲染： +```handlebars +{{#each subcategories}} + {{> category level=2}} +{{/each}} +``` + +**level参数的作用**: +- 用于跟踪当前嵌套层级 +- 控制标题标签的层级（h{{add level 1}}） +- 应用对应的CSS类（category-level-{{level}}） +- 传递给子组件以保持层级一致性 + +**使用示例**: +```handlebars + +{{> category category}} + + +{{> category category level=2}} +``` + +#### group.hbs - 分组容器组件 + +`group.hbs` 是用于在分类内组织站点的组件，同样支持层级参数。 + +**功能特性**: +- 支持在分类内创建站点分组 +- 自动应用层级样式 +- 支持展开/折叠功能 +- 与category.hbs保持一致的层级系统 + +**使用示例**: +```handlebars + +{{#each groups}} + {{> group}} +{{/each}} + + +{{> group group level=3}} +``` + +#### 多层级嵌套结构示例 + +典型的四层级结构：分类 → 子分类 → 分组 → 站点 + +```yaml +# 配置示例 +categories: + - name: "技术" + icon: "fas fa-code" + subcategories: + - name: "前端开发" + icon: "fas fa-laptop-code" + groups: + - name: "框架" + icon: "fas fa-cubes" + sites: + - name: "React" + url: "https://reactjs.org" + icon: "fab fa-react" + - name: "Vue" + url: "https://vuejs.org" + icon: "fab fa-vuejs" +``` + +对应的模板渲染： +```handlebars + +
+
+

技术

+
+
+
+ +
+
+

前端开发

+
+
+
+ +
+
+

框架

+
+
+
+ + {{> site-card site}} +
+
+
+
+
+
+
+
+
+``` + +#### 层级系统说明 + +- **层级1 (level=1)**: 顶级分类，使用h2标题 +- **层级2 (level=2)**: 子分类，使用h3标题 +- **层级3 (level=3)**: 分组，使用h4标题 +- **层级4+**: 更深层级，继续递增标题层级 + +每个层级都有对应的CSS类： +- `category-level-1`, `category-level-2`, ... +- `group-level-1`, `group-level-2`, ... + +这种设计确保了： +1. 语义化的HTML结构 +2. 一致的视觉层级 +3. 可扩展的嵌套深度 +4. 灵活的样式定制 + ### 站点图标渲染（favicon/manual） 当启用 `icons.mode: favicon`（默认）时，站点卡片会优先显示站点 favicon；当 URL 非 http/https、加载失败或网络受限，则自动回退到 Font Awesome 图标。相关助手：`ifHttpUrl`（条件）与 `encodeURIComponent`（工具）。