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

docs: 添加或修改各目录README文档

Browse Source
This commit is contained in:
Zuoling Rong
2025-05-09 01:09:55 +08:00
parent 4c3c5d23fa
commit 6924ce1c51
7 changed files with 387 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/deploy.yml vendored
View File

@@ -30,7 +30,7 @@ jobs:
- name: Setup Node.js - name: Setup Node.js
uses: actions/setup-node@v4 uses: actions/setup-node@v4
with: with:
node-version: '16' node-version: '18'
cache: 'npm' cache: 'npm'
- name: Install dependencies - name: Install dependencies

38
README.md
View File

@@ -65,6 +65,14 @@
<details> <details>
<summary>点击查看/隐藏更新日志</summary> <summary>点击查看/隐藏更新日志</summary>
### 2025/05/08
**1. Handlebars模板系统重构**
- ✅ 使用Handlebars模板引擎重构整个前端生成系统
- ✅ 实现模块化、组件化的模板结构，包含layouts、pages和components
- ✅ 改进代码复用，提高可维护性和扩展性
- ✅ 优化HTML生成逻辑，提升性能和代码质量
### 2025/05/04 ### 2025/05/04
**1. 移除双文件配置支持** **1. 移除双文件配置支持**
@@ -125,6 +133,7 @@
- HTML5 + CSS3 - HTML5 + CSS3
- JavaScript (原生) - JavaScript (原生)
- Handlebars 模板引擎
- Font Awesome 图标 - Font Awesome 图标
- GitHub Pages托管/其他各种CI/CD服务托管 - GitHub Pages托管/其他各种CI/CD服务托管
@@ -140,8 +149,18 @@ menav/
│ ├── bookmark-processor.js # 书签导入处理器 │ ├── bookmark-processor.js # 书签导入处理器
│ ├── migrate-config.js # 配置迁移工具 │ ├── migrate-config.js # 配置迁移工具
│ └── script.js # 前端JavaScript脚本 │ └── script.js # 前端JavaScript脚本
├── templates/ # HTML模板 ├── templates/ # Handlebars模板目录
│ └── index.html # HTML骨架模板文件 │ ├── layouts/ # 布局模板
│ │ └── default.hbs # 默认布局模板
│ ├── pages/ # 页面模板
│ │ ├── home.hbs # 首页模板
│ │ ├── projects.hbs # 项目页模板
│ │ └── ... # 其他页面模板
│ └── components/ # 可复用组件模板
│ ├── navigation.hbs # 导航组件
│ ├── category.hbs # 分类组件
│ ├── site-card.hbs # 站点卡片组件
│ └── ... # 其他组件
├── dist/ # 生成的静态网站（由generator.js生成） ├── dist/ # 生成的静态网站（由generator.js生成）
├── bookmarks/ # 书签导入目录 ├── bookmarks/ # 书签导入目录
├── config/ # 模块化配置目录 ├── config/ # 模块化配置目录
@@ -636,6 +655,21 @@ MeNav支持从浏览器导入书签，快速批量添加网站链接，无需手
模块化配置将不同功能的配置分散到多个文件中，便于管理和维护。当网站内容较多时，分散的配置文件让您可以只关注需要修改的特定部分，避免配置文件变得臃肿难以编辑。 模块化配置将不同功能的配置分散到多个文件中，便于管理和维护。当网站内容较多时，分散的配置文件让您可以只关注需要修改的特定部分，避免配置文件变得臃肿难以编辑。
</details> </details>
<details>
<summary>如何自定义Handlebars模板？</summary>
MeNav现在使用Handlebars模板系统，您可以通过以下步骤自定义模板：
1. **基本修改**：Fork项目后，您可以编辑`templates`目录下的模板文件
2. **结构说明**：
- `layouts`：包含整体页面布局模板
- `pages`：包含各页面的主要内容模板
- `components`：包含可复用的组件模板
3. **组件扩展**：创建新的组件模板时，需要在generator.js中注册，才能通过`{{> component-name}}`语法使用
4. **自定义页面**：新增页面需要在`templates/pages`添加模板，并确保有对应的配置文件
修改模板后，需要重新构建项目以应用更改。
</details>
<details> <details>
<summary>如何更改网站的主题或样式？</summary> <summary>如何更改网站的主题或样式？</summary>
目前MeNav采用统一的设计风格，您可以通过修改`config/user/site.yml`中的字体设置来调整网站外观。未来版本将考虑增加主题切换功能。 目前MeNav采用统一的设计风格，您可以通过修改`config/user/site.yml`中的字体设置来调整网站外观。未来版本将考虑增加主题切换功能。

72
assets/README.md Normal file
View File

@@ -0,0 +1,72 @@
# MeNav 资源目录
## 目录
- [目录概述](#目录概述)
- [资源列表](#资源列表)
- [资源使用说明](#资源使用说明)
- [添加新资源](#添加新资源)
## 目录概述
`assets` 目录包含 MeNav 项目所需的所有静态资源文件，包括样式表、图标、图片等。这些资源文件直接被复制到生成的站点中，用于网站的展示和功能实现。
## 资源列表
目录包含以下主要资源：
- **style.css**: 网站的主样式表文件
- 定义了网站的整体样式、布局和主题
- 包含响应式设计和动画效果的实现
- **favicon.ico**: 网站图标
- 显示在浏览器标签页、书签和收藏夹中
- 作为网站的标识符
- **preview_light.png**: 明亮主题预览图
- 用于README文档中展示网站明亮主题效果
- 作为项目展示素材
- **preview_dark.png**: 暗黑主题预览图
- 用于README文档中展示网站暗黑主题效果
- 作为项目展示素材
## 资源使用说明
### 样式表
`style.css` 文件包含网站的所有样式定义，遵循以下组织结构：
- 基础样式 - 通用元素样式定义
- 布局样式 - 页面结构和布局定义
- 组件样式 - 特定UI组件的样式定义
- 响应式样式 - 适配不同设备屏幕的媒体查询
- 主题样式 - 明亮和暗黑主题的颜色方案
样式表支持主题切换功能，通过CSS变量实现不同主题下的颜色变换。
### 图标与图片
- 网站图标 (`favicon.ico`) 自动应用于生成的网站
- 预览图片用于项目文档和宣传
## 添加新资源
向资源目录添加新文件时，请遵循以下指南：
1. **文件命名**:
- 使用小写字母和连字符 (`-`)
- 避免使用空格和特殊字符
- 名称应清晰表达文件用途
2. **图片优化**:
- 压缩图片以减小文件大小
- 使用适合web的格式 (PNG, JPG, WebP)
- 考虑添加合适的分辨率版本
3. **样式扩展**:
- 新的样式应该添加到 `style.css` 的合适部分
- 遵循现有的命名规范和组织结构
- 确保添加响应式设计支持
添加新资源后，构建系统会自动将这些文件复制到生成的网站中。

86
bookmarks/README.md Normal file
View File

@@ -0,0 +1,86 @@
# MeNav 书签目录
## 目录
- [目录概述](#目录概述)
- [功能说明](#功能说明)
- [书签导入流程](#书签导入流程)
- [支持的浏览器](#支持的浏览器)
- [书签格式要求](#书签格式要求)
- [文件处理机制](#文件处理机制)
## 目录概述
`bookmarks` 目录是 MeNav 项目中用于存放浏览器导出的书签文件的专用目录。该目录与书签导入功能直接关联，用于自动将浏览器书签转换为 MeNav 配置文件，从而快速生成个人导航站点。
## 功能说明
书签导入功能允许用户：
- 从浏览器导出书签为 HTML 文件
- 将书签文件放入此目录
- 通过自动处理将书签转换为网站配置
- 无需手动编辑即可批量导入网站链接
这一功能极大简化了网站内容的初始设置过程，特别适合需要迁移大量书签的用户。
## 书签导入流程
完整的书签导入流程如下：
1. 在浏览器中导出书签为 HTML 文件
2. 将导出的书签文件放入 `bookmarks` 目录
3. 运行书签处理工具：
```bash
npm run import-bookmarks
```
4. 系统自动解析书签文件内容
5. 根据书签文件夹结构生成分类
6. 生成配置文件保存到 `config/user/pages/bookmarks.yml`
7. 构建网站应用新配置：
```bash
npm run build
```
## 支持的浏览器
MeNav 书签导入功能支持从以下浏览器导出的书签文件：
- **Chrome** - 通过书签管理器导出
- **Firefox** - 通过书签库导出
- **Edge** - 通过收藏夹导出
- **Safari** - 通过书签菜单导出
- 其他支持标准 HTML 书签格式的浏览器
## 书签格式要求
导入的书签文件需满足以下要求：
- 文件格式：HTML（标准网络书签格式）
- 文件编码：UTF-8
- 文件结构：包含 `<DL>`、`<DT>` 和 `<A>` 标签的标准书签结构
- 文件大小：建议不超过 5MB（约数千个书签）
## 文件处理机制
书签处理器 (`src/bookmark-processor.js`) 对书签文件进行以下处理：
1. **解析文件结构**：
- 读取书签 HTML 文件
- 解析 DOM 结构获取书签层次
- 提取文件夹和链接信息
2. **分类提取**：
- 将书签文件夹转换为网站分类
- 提取链接URL、标题和添加日期
3. **图标分配**：
- 根据URL自动匹配合适的 Font Awesome 图标
- 为每个链接和分类分配图标
4. **配置生成**：
- 创建符合 MeNav 配置格式的 YAML 文件
- 按层级组织分类和链接
- 应用自动生成的元数据
将书签放入此目录后，您可以立即利用 MeNav 的书签处理功能，快速将书签转化为个性化导航站点。

177
config/README.md Normal file
View File

@@ -0,0 +1,177 @@
# MeNav 配置目录
## 目录
- [目录概述](#目录概述)
- [配置目录结构](#配置目录结构)
- [配置加载机制](#配置加载机制)
- [模块化配置文件](#模块化配置文件)
- [网站基础配置](#网站基础配置)
- [导航配置](#导航配置)
- [页面配置](#页面配置)
- [配置优先级](#配置优先级)
- [配置示例](#配置示例)
- [最佳实践](#最佳实践)
## 目录概述
`config` 目录包含 MeNav 项目的所有配置文件，采用模块化的 YAML 格式组织。这些配置文件定义了网站的内容、结构、布局和功能，是定制个人导航站的核心。
## 配置目录结构
配置系统采用分层结构，清晰分离默认配置和用户配置：
```
config/
├── _default/ # 默认配置目录
│ ├── site.yml # 默认网站基础配置
│ ├── navigation.yml # 默认导航配置
│ └── pages/ # 默认页面配置
│ ├── home.yml # 首页默认配置
│ ├── projects.yml
│ ├── articles.yml
│ ├── friends.yml
│ └── bookmarks.yml
└── user/ # 用户配置目录（覆盖默认配置）
├── site.yml # 用户自定义网站配置
├── navigation.yml # 用户自定义导航配置
└── pages/ # 用户自定义页面配置
├── home.yml # 首页用户配置
└── ...
```
## 配置加载机制
MeNav 配置系统使用深度合并机制，按以下顺序加载和合并配置：
1. 加载 `_default` 目录中的所有配置（基础层）
2. 加载 `user` 目录中的配置（如果存在，覆盖同名配置项）
3. 深度合并所有配置，确保用户配置优先级高于默认配置
4. 应用最终合并后的配置生成网站
这种机制使用户只需配置想要自定义的部分，其余部分由默认配置提供。
## 模块化配置文件
### 网站基础配置
`site.yml` 定义网站的基本信息和全局设置：
- 网站标题、描述和关键词
- 作者信息和版权声明
- 字体配置和主题设置
- 全局元数据和站点参数
- 个人资料和社交媒体链接
### 导航配置
`navigation.yml` 定义网站的导航结构：
- 侧边栏导航项
- 页面标题和图标
- 页面顺序和可见性
- 外部链接配置
### 页面配置
`pages/` 目录下的配置文件定义各个页面的内容：
- `home.yml`: 首页分类和站点列表
- `projects.yml`: 项目展示配置
- `articles.yml`: 文章列表配置
- `friends.yml`: 友情链接配置
- `bookmarks.yml`: 书签页面配置
- 自定义页面配置
## 配置优先级
配置项的优先级从高到低为：
1. 用户页面配置 (`user/pages/*.yml`)
2. 用户导航配置 (`user/navigation.yml`)
3. 用户网站配置 (`user/site.yml`)
4. 默认页面配置 (`_default/pages/*.yml`)
5. 默认导航配置 (`_default/navigation.yml`)
6. 默认网站配置 (`_default/site.yml`)
## 配置示例
### 网站配置示例 (site.yml)
```yaml
# 网站基本信息
title: "我的个人导航"
description: "个人收藏的网站导航页"
keywords: "导航,网址,书签,个人主页"
# 个人资料配置
profile:
title: "个人导航站"
subtitle: "我收藏的精选网站"
description: "这是一个用于快速访问常用网站的个人导航页面。"
# 主题和样式设置
theme:
default: "light"
toggleIcon: true
# 字体配置
fonts:
title: "Roboto, sans-serif"
content: "Noto Sans SC, sans-serif"
# 社交媒体链接
social:
- name: "GitHub"
url: "https://github.com/username"
icon: "fab fa-github"
- name: "Twitter"
url: "https://twitter.com/username"
icon: "fab fa-twitter"
```
### 首页配置示例 (home.yml)
```yaml
# 首页分类配置
categories:
- name: "常用工具"
icon: "fas fa-tools"
sites:
- name: "Google"
url: "https://www.google.com"
description: "全球最大的搜索引擎"
icon: "fab fa-google"
- name: "GitHub"
url: "https://github.com"
description: "代码托管平台"
icon: "fab fa-github"
- name: "学习资源"
icon: "fas fa-graduation-cap"
sites:
- name: "MDN Web Docs"
url: "https://developer.mozilla.org"
description: "Web开发技术文档"
icon: "fab fa-firefox-browser"
```
## 最佳实践
1. **目录结构**:
- 总是在 `user/` 目录下创建您的配置
- 不要直接修改 `_default/` 中的文件
2. **文件命名**:
- 遵循现有的文件命名约定
- 自定义页面配置应使用有意义的名称
3. **配置管理**:
- 利用模块化结构分类管理配置
- 只覆盖需要自定义的配置项
- 定期备份您的用户配置
4. **配置验证**:
- 修改配置后先在本地构建测试
- 使用 `npm run dev` 预览更改效果
- 确保 YAML 语法正确无误

15
src/README.md
View File

@@ -1,4 +1,17 @@
# MeNav 源代码目录结构 # MeNav 源代码目录
## 目录
- [目录概述](#目录概述)
- [源代码结构分工](#源代码结构分工)
- [根目录函数（核心功能）](#根目录函数核心功能)
- [helpers 目录函数（辅助功能）](#helpers-目录函数辅助功能)
- [函数职责分工](#函数职责分工)
- [核心函数（根目录）](#核心函数根目录)
- [辅助函数（helpers目录）](#辅助函数helpers目录)
- [扩展和修改指南](#扩展和修改指南)
- [添加新的核心功能](#添加新的核心功能)
- [添加新的辅助函数](#添加新的辅助函数)
## 目录概述 ## 目录概述

2
templates/README.md
View File

@@ -1,4 +1,4 @@
# MeNav 模板系统说明文档 # MeNav 模板目录
## 目录 ## 目录