chill/menav
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

docs: 更新文档

Browse Source
This commit is contained in:
coolzr
2025-10-24 01:28:37 +08:00
parent 6359829298
commit da1e3fedd6
3 changed files with 223 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
README.md
View File

@@ -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:
提示：更改配置后重新构建即可生效。
</details>
<details>
<summary>如何从旧式配置迁移到模块化配置？</summary>
由于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。
</details>
<details>
<summary>如何使用MarksVault扩展自动同步书签？</summary>

3
src/README.md
View File

@@ -40,9 +40,6 @@
- 转换浏览器书签为MeNav配置格式
- 提供书签导入功能
- **migrate-config.js**: 配置迁移工具
- 处理配置文件格式升级
- 确保向后兼容性
### helpers 目录函数（辅助功能）

137
templates/README.md
View File

@@ -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
<!-- category.hbs 会递归渲染 -->
<section class="category category-level-1" data-level="1">
<div class="category-header">
<h2><i class="fas fa-code"></i> 技术</h2>
</div>
<div class="category-content">
<div class="subcategories-container">
<!-- 递归调用 category.hbs，level=2 -->
<section class="category category-level-2" data-level="2">
<div class="category-header">
<h3><i class="fas fa-laptop-code"></i> 前端开发</h3>
</div>
<div class="category-content">
<div class="groups-container">
<!-- 使用 group.hbs，默认 level=3 -->
<div class="group group-level-3" data-level="3">
<div class="group-header">
<h4><i class="fas fa-cubes"></i> 框架</h4>
</div>
<div class="group-content">
<div class="sites-grid">
<!-- 渲染站点卡片 -->
{{> site-card site}}
</div>
</div>
</div>
</div>
</div>
</section>
</div>
</div>
</section>
```
#### 层级系统说明
- **层级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`（工具）。