From 6924ce1c511947ddd1e075f42764f90e58f2db78 Mon Sep 17 00:00:00 2001 From: Zuoling Rong Date: Fri, 9 May 2025 01:09:55 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E6=88=96=E4=BF=AE?= =?UTF-8?q?=E6=94=B9=E5=90=84=E7=9B=AE=E5=BD=95README=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/deploy.yml | 2 +- README.md | 38 +++++++- assets/README.md | 72 ++++++++++++++ bookmarks/README.md | 86 +++++++++++++++++ config/README.md | 177 +++++++++++++++++++++++++++++++++++ src/README.md | 15 ++- templates/README.md | 2 +- 7 files changed, 387 insertions(+), 5 deletions(-) create mode 100644 assets/README.md create mode 100644 bookmarks/README.md create mode 100644 config/README.md diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 1705c4e..664bd84 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -30,7 +30,7 @@ jobs: - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version: '16' + node-version: '18' cache: 'npm' - name: Install dependencies diff --git a/README.md b/README.md index 73432ab..f7a330c 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,14 @@
点击查看/隐藏更新日志 +### 2025/05/08 + +**1. Handlebars模板系统重构** +- ✅ 使用Handlebars模板引擎重构整个前端生成系统 +- ✅ 实现模块化、组件化的模板结构，包含layouts、pages和components +- ✅ 改进代码复用，提高可维护性和扩展性 +- ✅ 优化HTML生成逻辑，提升性能和代码质量 + ### 2025/05/04 **1. 移除双文件配置支持** @@ -125,6 +133,7 @@ - HTML5 + CSS3 - JavaScript (原生) +- Handlebars 模板引擎 - Font Awesome 图标 - GitHub Pages托管/其他各种CI/CD服务托管 @@ -140,8 +149,18 @@ menav/ │ ├── bookmark-processor.js # 书签导入处理器 │ ├── migrate-config.js # 配置迁移工具 │ └── script.js # 前端JavaScript脚本 -├── templates/ # HTML模板 -│ └── index.html # HTML骨架模板文件 +├── templates/ # Handlebars模板目录 +│ ├── layouts/ # 布局模板 +│ │ └── default.hbs # 默认布局模板 +│ ├── pages/ # 页面模板 +│ │ ├── home.hbs # 首页模板 +│ │ ├── projects.hbs # 项目页模板 +│ │ └── ... # 其他页面模板 +│ └── components/ # 可复用组件模板 +│ ├── navigation.hbs # 导航组件 +│ ├── category.hbs # 分类组件 +│ ├── site-card.hbs # 站点卡片组件 +│ └── ... # 其他组件 ├── dist/ # 生成的静态网站（由generator.js生成） ├── bookmarks/ # 书签导入目录 ├── config/ # 模块化配置目录 @@ -636,6 +655,21 @@ MeNav支持从浏览器导入书签，快速批量添加网站链接，无需手 模块化配置将不同功能的配置分散到多个文件中，便于管理和维护。当网站内容较多时，分散的配置文件让您可以只关注需要修改的特定部分，避免配置文件变得臃肿难以编辑。
+
+如何自定义Handlebars模板？ +MeNav现在使用Handlebars模板系统，您可以通过以下步骤自定义模板： + +1. **基本修改**：Fork项目后，您可以编辑`templates`目录下的模板文件 +2. **结构说明**： + - `layouts`：包含整体页面布局模板 + - `pages`：包含各页面的主要内容模板 + - `components`：包含可复用的组件模板 +3. **组件扩展**：创建新的组件模板时，需要在generator.js中注册，才能通过`{{> component-name}}`语法使用 +4. **自定义页面**：新增页面需要在`templates/pages`添加模板，并确保有对应的配置文件 + +修改模板后，需要重新构建项目以应用更改。 +
+
如何更改网站的主题或样式？ 目前MeNav采用统一的设计风格，您可以通过修改`config/user/site.yml`中的字体设置来调整网站外观。未来版本将考虑增加主题切换功能。 diff --git a/assets/README.md b/assets/README.md new file mode 100644 index 0000000..fb8d3cc --- /dev/null +++ b/assets/README.md @@ -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` 的合适部分 + - 遵循现有的命名规范和组织结构 + - 确保添加响应式设计支持 + +添加新资源后，构建系统会自动将这些文件复制到生成的网站中。 \ No newline at end of file diff --git a/bookmarks/README.md b/bookmarks/README.md new file mode 100644 index 0000000..cabeb83 --- /dev/null +++ b/bookmarks/README.md @@ -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 +- 文件结构：包含 `
`、`
` 和 `` 标签的标准书签结构 +- 文件大小：建议不超过 5MB（约数千个书签） + +## 文件处理机制 + +书签处理器 (`src/bookmark-processor.js`) 对书签文件进行以下处理： + +1. **解析文件结构**： + - 读取书签 HTML 文件 + - 解析 DOM 结构获取书签层次 + - 提取文件夹和链接信息 + +2. **分类提取**： + - 将书签文件夹转换为网站分类 + - 提取链接URL、标题和添加日期 + +3. **图标分配**： + - 根据URL自动匹配合适的 Font Awesome 图标 + - 为每个链接和分类分配图标 + +4. **配置生成**： + - 创建符合 MeNav 配置格式的 YAML 文件 + - 按层级组织分类和链接 + - 应用自动生成的元数据 + +将书签放入此目录后，您可以立即利用 MeNav 的书签处理功能，快速将书签转化为个性化导航站点。 \ No newline at end of file diff --git a/config/README.md b/config/README.md new file mode 100644 index 0000000..fc08f18 --- /dev/null +++ b/config/README.md @@ -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 语法正确无误 \ No newline at end of file diff --git a/src/README.md b/src/README.md index 30d8411..15e840e 100644 --- a/src/README.md +++ b/src/README.md @@ -1,4 +1,17 @@ -# MeNav 源代码目录结构 +# MeNav 源代码目录 + +## 目录 + +- [目录概述](#目录概述) +- [源代码结构分工](#源代码结构分工) + - [根目录函数（核心功能）](#根目录函数核心功能) + - [helpers 目录函数（辅助功能）](#helpers-目录函数辅助功能) +- [函数职责分工](#函数职责分工) + - [核心函数（根目录）](#核心函数根目录) + - [辅助函数（helpers目录）](#辅助函数helpers目录) +- [扩展和修改指南](#扩展和修改指南) + - [添加新的核心功能](#添加新的核心功能) + - [添加新的辅助函数](#添加新的辅助函数) ## 目录概述 diff --git a/templates/README.md b/templates/README.md index 70f53de..e5de618 100644 --- a/templates/README.md +++ b/templates/README.md @@ -1,4 +1,4 @@ -# MeNav 模板系统说明文档 +# MeNav 模板目录 ## 目录