docs: 更新文档
This commit is contained in:
coolzr
112
README.md
112
README.md
@@ -66,6 +66,7 @@
|
|||||||
- 👥 支持展示社交媒体链接
|
- 👥 支持展示社交媒体链接
|
||||||
- 📝 支持多个内容页面
|
- 📝 支持多个内容页面
|
||||||
- 📌 支持从浏览器导入书签
|
- 📌 支持从浏览器导入书签
|
||||||
|
- 📚 支持2-4层级的多层级嵌套书签结构，更好地组织内容
|
||||||
- 🔄 与 [MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展集成，支持自动推送书签
|
- 🔄 与 [MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展集成，支持自动推送书签
|
||||||
- 🧩 模块化配置
|
- 🧩 模块化配置
|
||||||
- 🔄 可部署到GitHub Pages或任何类似的CI/CD服务，及任何服务器
|
- 🔄 可部署到GitHub Pages或任何类似的CI/CD服务，及任何服务器
|
||||||
@@ -145,7 +146,6 @@ icons:
|
|||||||
**1. 移除双文件配置支持**
|
**1. 移除双文件配置支持**
|
||||||
- ✅ 完全移除了对双文件配置方法的支持
|
- ✅ 完全移除了对双文件配置方法的支持
|
||||||
- ✅ 简化了配置加载逻辑，现在仅支持模块化配置
|
- ✅ 简化了配置加载逻辑，现在仅支持模块化配置
|
||||||
- ✅ 保留配置迁移工具
|
|
||||||
|
|
||||||
### 2025/05/03
|
### 2025/05/03
|
||||||
|
|
||||||
@@ -209,7 +209,6 @@ menav/
|
|||||||
├── src/ # 源代码
|
├── src/ # 源代码
|
||||||
│ ├── generator.js # 静态网站生成器
|
│ ├── generator.js # 静态网站生成器
|
||||||
│ ├── bookmark-processor.js # 书签导入处理器
|
│ ├── bookmark-processor.js # 书签导入处理器
|
||||||
│ ├── migrate-config.js # 配置迁移工具
|
|
||||||
│ └── script.js # 前端JavaScript脚本
|
│ └── script.js # 前端JavaScript脚本
|
||||||
├── templates/ # Handlebars模板目录
|
├── templates/ # Handlebars模板目录
|
||||||
│ ├── layouts/ # 布局模板
|
│ ├── layouts/ # 布局模板
|
||||||
@@ -597,6 +596,92 @@ categories: # 该页面的分类和网站
|
|||||||
description: "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）配置无需修改即可继续使用
|
||||||
|
- 系统会自动检测配置结构并应用相应的模板和样式
|
||||||
|
- 可以在同一配置中混合使用不同层级结构（某些分类使用二级结构，某些使用三级或四级结构）
|
||||||
|
- 模板系统会自动处理不同层级结构，无需手动指定模板类型
|
||||||
|
|
||||||
|
|
||||||
> **📝提示**：
|
> **📝提示**：
|
||||||
> - 每个页面可以拥有不同的分类和网站
|
> - 每个页面可以拥有不同的分类和网站
|
||||||
@@ -799,29 +884,6 @@ icons:
|
|||||||
提示：更改配置后重新构建即可生效。
|
提示：更改配置后重新构建即可生效。
|
||||||
</details>
|
</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>
|
<details>
|
||||||
<summary>如何使用MarksVault扩展自动同步书签？</summary>
|
<summary>如何使用MarksVault扩展自动同步书签？</summary>
|
||||||
|
|||||||
@@ -40,9 +40,6 @@
|
|||||||
- 转换浏览器书签为MeNav配置格式
|
- 转换浏览器书签为MeNav配置格式
|
||||||
- 提供书签导入功能
|
- 提供书签导入功能
|
||||||
|
|
||||||
- **migrate-config.js**: 配置迁移工具
|
|
||||||
- 处理配置文件格式升级
|
|
||||||
- 确保向后兼容性
|
|
||||||
|
|
||||||
### helpers 目录函数（辅助功能）
|
### helpers 目录函数（辅助功能）
|
||||||
|
|
||||||
|
|||||||
@@ -8,6 +8,7 @@
|
|||||||
- [布局模板](#布局模板)
|
- [布局模板](#布局模板)
|
||||||
- [页面模板](#页面模板)
|
- [页面模板](#页面模板)
|
||||||
- [组件模板](#组件模板)
|
- [组件模板](#组件模板)
|
||||||
|
- [多层级嵌套模板组件](#多层级嵌套模板组件)
|
||||||
- [模板数据流](#模板数据流)
|
- [模板数据流](#模板数据流)
|
||||||
- [模板使用示例](#模板使用示例)
|
- [模板使用示例](#模板使用示例)
|
||||||
- [最佳实践](#最佳实践)
|
- [最佳实践](#最佳实践)
|
||||||
@@ -113,7 +114,8 @@ templates/
|
|||||||
**主要组件**:
|
**主要组件**:
|
||||||
- `navigation.hbs` - 导航菜单
|
- `navigation.hbs` - 导航菜单
|
||||||
- `site-card.hbs` - 站点卡片
|
- `site-card.hbs` - 站点卡片
|
||||||
- `category.hbs` - 分类容器
|
- `category.hbs` - 分类容器（支持多层级嵌套）
|
||||||
|
- `group.hbs` - 分组容器（支持多层级嵌套）
|
||||||
- `social-links.hbs` - 社交链接
|
- `social-links.hbs` - 社交链接
|
||||||
- `search-results.hbs` - 搜索结果展示
|
- `search-results.hbs` - 搜索结果展示
|
||||||
|
|
||||||
@@ -128,6 +130,139 @@ templates/
|
|||||||
{{/if}}
|
{{/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）
|
### 站点图标渲染（favicon/manual）
|
||||||
|
|
||||||
当启用 `icons.mode: favicon`（默认）时，站点卡片会优先显示站点 favicon；当 URL 非 http/https、加载失败或网络受限，则自动回退到 Font Awesome 图标。相关助手：`ifHttpUrl`（条件）与 `encodeURIComponent`（工具）。
|
当启用 `icons.mode: favicon`（默认）时，站点卡片会优先显示站点 favicon；当 URL 非 http/https、加载失败或网络受限，则自动回退到 Font Awesome 图标。相关助手：`ifHttpUrl`（条件）与 `encodeURIComponent`（工具）。
|
||||||
|
|||||||
Reference in New Issue
Block a user