diff --git a/README.md b/README.md index fd4e2b2..35c81f1 100644 --- a/README.md +++ b/README.md @@ -36,10 +36,8 @@ - [部署到GitHub Pages](#快速部署到github-pages) - [部署到自己的服务器](#部署到服务器) - [其他CI/CD服务部署](#其他cicd托管选项) -- [配置指南](#设置配置文件) - - [配置方式对比](#配置方式对比) - - [双文件配置](#使用双文件配置) - - [模块化配置(推荐)](#使用模块化配置) +- [配置指南](#设置模块化配置文件) + - [使用配置](#使用配置) - [配置详解](#配置详解) - [书签导入](#书签导入功能) - [常见问题](#常见问题) @@ -59,7 +57,7 @@ - 👥 支持展示社交媒体链接 - 📝 支持多个内容页面 - 📌 支持从浏览器导入书签 -- 🧩 模块化配置/双文件配置 +- 🧩 模块化配置 - 🔄 可部署到GitHub Pages或任何类似的CI/CD服务,及任何服务器 ## 近期更新 @@ -67,6 +65,13 @@
点击查看/隐藏更新日志 +### 2025/05/04 + +**1. 移除双文件配置支持** +- ✅ 完全移除了对双文件配置方法的支持 +- ✅ 简化了配置加载逻辑,现在仅支持模块化配置 +- ✅ 保留配置迁移工具 + ### 2025/05/03 **1. 侧边栏收回功能** @@ -132,6 +137,8 @@ menav/ │ └── favicon.ico # 网站图标 ├── src/ # 源代码 │ ├── generator.js # 静态网站生成器 +│ ├── bookmark-processor.js # 书签导入处理器 +│ ├── migrate-config.js # 配置迁移工具 │ └── script.js # 前端JavaScript脚本 ├── templates/ # HTML模板 │ └── index.html # HTML骨架模板文件 @@ -151,8 +158,6 @@ menav/ │ ├── site.yml # 用户网站配置 │ ├── navigation.yml # 用户导航配置 │ └── pages/ # 用户页面配置 -├── config.yml # 默认配置文件(传统格式) -└── config.user.yml # 用户自定义配置文件(传统格式) ``` ## 快速开始 @@ -175,9 +180,9 @@ npm install ``` 3. 修改配置 - - 根据您的需求选择配置方式: - - 双文件配置:复制`config.yml`为`config.user.yml`并编辑 - - 模块化配置:在`config/user/`目录下创建配置文件 + - 在`config/user/`目录下创建配置文件 + - 至少需要创建`site.yml`和`navigation.yml` + - 可以参考`config/_default/`目录结构和内容 - 自定义站点标题、描述、导航链接和网站分类等 4. 本地预览 @@ -227,8 +232,7 @@ npm run build 1. 创建个人配置文件: - **重要:** 始终创建自己的用户配置文件,不要直接修改默认配置文件 - - 可以使用双文件配置或模块化配置 - - 推荐使用模块化配置(见[使用模块化配置](#使用模块化配置)) + - 使用模块化配置(见[使用模块化配置](#使用模块化配置)) - 提交您的配置文件到仓库 2. 等待自动部署: @@ -326,62 +330,21 @@ server {
-## 设置配置文件 +## 设置模块化配置文件 -MeNav支持两种配置方式:双文件配置和模块化配置(推荐)。 +MeNav使用模块化配置方式,将配置分散到多个文件中,更易于管理和维护。 -> **🔔 重要提示:** 请务必创建并使用您自己的配置文件(`config.user.yml`或`config/user/`目录),不要直接修改默认配置文件,以便后续更新项目时不会丢失您的个性化设置。 +> **🔔 重要提示:** 请务必在`config/user/`目录下创建并使用您自己的配置文件,不要直接修改默认配置文件,以便后续更新项目时不会丢失您的个性化设置。 在加载配置时遵循以下优先级顺序: 1. `config/user/` (模块化用户配置)(优先级最高) -2. `config.user.yml`和 `bookmarks.user.yml`(双文件用户配置) -3. `config/_default/` (模块化默认配置) -4. `config.yml`和`bookmarks.yml`(双文件默认配置)(优先级最低) +2. `config/_default/` (模块化默认配置) -**注意:** 各优先级配置间采用完全替换策略,而非合并。系统会选择存在的最高优先级配置,完全忽略其他低优先级配置。这确保了模块化配置和双文件配置都能独立使用,避免混合配置带来的意外行为。 +**注意:** 采用完全替换策略,而非合并。系统会选择存在的用户配置,完全忽略默认配置。 -### 配置方式对比 +### 使用配置 - - - - - - - - - - - - - - - - - - - - - - - - - - -
特性双文件配置模块化配置(推荐)
配置文件两个主要文件:config.user.ymlbookmarks.user.yml分散到多个文件:config/user/site.yml, navigation.yml, pages/*.yml
适用场景小型网站,快速开始复杂网站,长期维护
关注点分离所有配置集中在一个文件每个页面和功能区域有专属配置文件
兼容性传统方式,简单直接完全兼容传统方式,不影响旧版本
- -### 使用双文件配置 - -双文件配置由 `config.yml`/`config.user.yml` 和 `bookmarks.yml`/`bookmarks.user.yml` 两个文件组成,适合小型网站和快速开始。 - -* **创建配置文件**: - - 复制 `config.yml` 为 `config.user.yml` - - 对于书签配置,请勿手动创建 `bookmarks.user.yml`,它应通过[书签导入功能](#书签导入功能)自动生成 - - 编辑 `config.user.yml` 添加您的配置 - -### 使用模块化配置 - -模块化配置将配置分散到多个文件中,更易于管理和维护,推荐用于复杂网站。 +模块化配置将配置分散到多个文件中,更易于管理和维护。 * **创建配置目录**: - 在`config/user/`目录下创建您的自定义配置文件 @@ -393,25 +356,27 @@ MeNav支持两种配置方式:双文件配置和模块化配置(推荐)。
点击展开 -以下是配置文件的详细说明,帮助您全面了解和定制您的个人导航站。本指南适用于双文件配置和模块化配置两种方式。 +MeNav的配置系统分为三个主要部分,对应三种不同类型的配置文件: -#### 1. 基础网站配置 (site) +1. `site.yml` - 网站基本信息、字体、个人资料和社交媒体链接 +2. `navigation.yml` - 导航菜单配置 +3. `pages/` 目录 - 各页面的内容配置 -网站的基本信息配置,这些设置会影响整个网站的呈现: +以下详细介绍每个配置文件的结构和用途。 + +### 一、site.yml 配置文件 + +site.yml文件包含网站的基本信息、字体设置、个人资料和社交媒体链接等全局配置,这些设置会影响整个网站的呈现。 ```yaml -site: - title: "我的导航站" # 网站标题,显示在浏览器标签和页面顶部 - description: "个人网址导航" # 网站描述,用于SEO和分享卡片 - author: "张三" # 作者姓名 - favicon: "favicon.ico" # 网站图标,支持ico、png等格式 -``` +# 网站基本信息 +title: "我的导航站" # 网站标题,显示在浏览器标签和页面顶部 +description: "个人网址导航" # 网站描述,用于SEO和分享卡片 +author: "张三" # 作者姓名 +favicon: "favicon.ico" # 网站图标,支持ico、png等格式 +logo_text: "导航站" # 左上角显示的Logo文本 -#### 2. 字体设置 (fonts) - -MeNav支持自定义字体,您可以分别为标题、副标题和正文设置不同的字体: - -```yaml +# 字体设置 fonts: title: # 标题字体设置 family: "Roboto" # 字体名称 @@ -425,54 +390,72 @@ fonts: family: "Noto Sans SC" weight: 400 source: "google" -``` - -> **📝 温馨提示**: -> - **system**表示使用系统自带字体,无需额外加载,页面加载速度更快 -> - **google**表示从Google Fonts加载字体,选择更丰富,但可能影响加载速度 -> - 中文网站推荐使用"Noto Sans SC"、"Source Han Sans CN"等支持中文的字体 -> - 设置字重时请确保所选字体支持该字重值,否则可能无法正确显示 - -#### 3. 个人资料配置 (profile) - -设置首页顶部的个人欢迎区域: - -```yaml + +# 个人资料配置 profile: title: "欢迎来到我的导航站" # 主标题/欢迎语 subtitle: "收集实用网站和工具" # 副标题 description: "这里整理了我日常使用的网站和工具,方便快速访问。" # 详细描述 -``` -> **📝 温馨提示**:description支持较长文本,可以添加一些个性化的介绍或使用说明,让您的导航站更具特色。 - -#### 4. 导航菜单配置 (navigation) - -设置网站左侧的导航菜单,支持多个自定义页面: - -```yaml -navigation: - - name: "首页" # 菜单项名称 - icon: "fas fa-home" # 菜单项图标 - id: "home" # 页面标识符(必须唯一) - active: true # 是否默认激活(只能有一个为true) - - name: "项目" - icon: "fas fa-project-diagram" - id: "projects" - active: false - # 更多导航项... +# 社交媒体链接 +social: + - name: "GitHub" + url: "https://github.com/your-username" + icon: "fab fa-github" + - name: "Twitter" + url: "https://twitter.com/your-username" + icon: "fab fa-twitter" + # 更多社交媒体... ``` > **📝 温馨提示**: -> - 每个导航项的`id`必须唯一,并且有对应的页面配置(使用模块化配置时,每个导航项的`id`必须与`pages/`文件夹中的页面配置文件名一致) -> - 只能设置一个导航项的`active`为`true`,作为默认显示页面 -> - 图标使用Font Awesome 5图标库,格式为`前缀 fa-图标名` +> - 关于**字体设置**: +> - **system**表示使用系统自带字体,无需额外加载,页面加载速度更快 +> - **google**表示从Google Fonts加载字体,选择更丰富,但可能影响加载速度 +> - 中文网站推荐使用"Noto Sans SC"、"Source Han Sans CN"等支持中文的字体 +> - 设置字重时请确保所选字体支持该字重值,否则可能无法正确显示 +> - 关于**个人资料**:profile.description支持较长文本,可以添加一些个性化的介绍或使用说明,让您的导航站更具特色 +> - 关于**社交媒体链接**:这些链接会显示在网站侧边栏的底部,方便访问者联系您 -#### 5. 分类和网站配置 (categories) +### 二、navigation.yml 配置文件 -这是MeNav的核心配置,用于定义网站分类和链接: +navigation.yml文件定义网站左侧的导航菜单,支持添加多个自定义页面: ```yaml +# 导航菜单配置示例 +- name: "首页" # 菜单项名称 + icon: "fas fa-home" # 菜单项图标 + id: "home" # 页面标识符(必须唯一) + active: true # 是否默认激活(只能有一个为true) +- name: "项目" + icon: "fas fa-project-diagram" + id: "projects" + active: false +- name: "文章" + icon: "fas fa-book" + id: "articles" + active: false +# 更多导航项... +``` + +> **📝 温馨提示**: +> - 每个导航项的`id`必须唯一,并且有对应的页面配置文件(该id必须与`pages/`文件夹中的页面配置文件名一致) +> - 只能设置一个导航项的`active`为`true`,作为默认显示页面 +> - 图标使用Font Awesome 5图标库,格式为`前缀 fa-图标名` +> - 导航菜单的顺序与此配置文件中的顺序一致,可以通过调整项目顺序来更改导航顺序 + +### 三、pages目录 配置文件 + +pages目录包含每个页面的详细配置,每个文件对应一个页面。文件名必须与navigation.yml中的id一致。 + +例如,对于导航中的"home"页面,需要创建`config/user/pages/home.yml`: + +```yaml +# pages/home.yml示例 +title: "我的主页" # 页面标题 +subtitle: "常用网站导航" # 页面副标题 + +# 分类和网站配置 categories: - name: "常用工具" # 分类名称 icon: "fas fa-tools" # 分类图标 @@ -489,12 +472,38 @@ categories: # 更多分类... ``` -> **📝 温馨提示**: +自定义页面配置示例(以"notes"为例): + +1. 首先在navigation.yml中添加对应的导航项: +```yaml +- name: "笔记" + icon: "fas fa-sticky-note" + id: "notes" + active: false +``` + +2. 然后创建`config/user/pages/notes.yml`配置文件: +```yaml +title: "我的笔记收藏" # 页面标题 +subtitle: "学习和工作笔记资源" # 页面副标题 +categories: # 该页面的分类和网站 + - name: "编程笔记" + icon: "fas fa-code" + sites: + - name: "Python学习笔记" + url: "https://example.com/python-notes" + icon: "fab fa-python" + description: "Python编程技巧和案例" + # 更多网站... +``` + +> **📝提示**: > - 每个页面可以拥有不同的分类和网站 > - 网站描述建议简洁明了,不超过30个字符,以确保显示美观 -> - 合理组织分类和网站顺序,将常用网站放在前面,提升使用体验 +> - 不同页面可以特化用于不同用途,如"工作"、"学习"、"娱乐"等 +> - 页面数量不限,但建议控制在合理范围内,避免导航过长 -#### 6. Font Awesome图标指南 +### 四、Font Awesome图标指南 MeNav使用Font Awesome 5图标库,提供了丰富的图标选择: @@ -513,92 +522,27 @@ MeNav使用Font Awesome 5图标库,提供了丰富的图标选择: - 对于通用功能网站,选择能代表其功能的图标,如词典类用`fas fa-book` - 对于工具类网站,可使用`fas fa-tools`或更具体的工具图标 +### 五、配置文件结构示例 -#### 7. 自定义页面配置 - -MeNav支持创建任意数量的自定义页面,每个页面可以有不同内容: - -**第一步:在导航配置中添加页面入口** - -```yaml -# 在navigation.yml或config.user.yml的navigation部分添加 -- name: "笔记" - icon: "fas fa-sticky-note" - id: "notes" - active: false -``` - -**第二步:创建页面内容配置** - -模块化配置方式(在`config/user/pages/notes.yml`): -```yaml -title: "我的笔记收藏" # 页面标题 -subtitle: "学习和工作笔记资源" # 页面副标题 -categories: # 该页面的分类和网站 - - name: "编程笔记" - icon: "fas fa-code" - sites: - - name: "Python学习笔记" - url: "https://example.com/python-notes" - icon: "fab fa-python" - description: "Python编程技巧和案例" - # 更多网站... -``` - -双文件配置方式(在`config.user.yml`中): -```yaml -notes: # 与navigation中的id保持一致 - title: "我的笔记收藏" - subtitle: "学习和工作笔记资源" - categories: - # 与上面模块化配置内容相同 -``` - -> **📝 温馨提示**: -> - 页面标识符(`id`)在导航和页面配置中必须保持一致 -> - 每个页面支持独立的标题、副标题和分类设置 -> - 不同页面可以特化用于不同用途,如"工作"、"学习"、"娱乐"等 -> - 页面数量不限,但建议控制在合理范围内,避免导航过长 - -#### 8. 配置文件结构示例 - -**模块化配置示例**(推荐): +**完整配置结构**: ``` config/user/ -├── site.yml # 包含site、fonts、profile配置 +├── site.yml # 网站基本信息、字体、个人资料和社交媒体链接 ├── navigation.yml # 导航菜单配置 └── pages/ ├── home.yml # 首页配置 ├── projects.yml # 项目页配置 + ├── articles.yml # 文章页配置 + ├── friends.yml # 朋友页配置 └── notes.yml # 自定义笔记页配置 ``` -**双文件配置示例**: - -```yaml -# config.user.yml -site: - # 网站基本信息... -fonts: - # 字体设置... -profile: - # 个人信息... -navigation: - # 导航菜单... -home: - # 首页设置... -projects: - # 项目页设置... -notes: - # 自定义笔记页设置... -``` - -#### 9. 常见配置问题解决 +### 六、常见配置问题解决 1. **配置后不生效** - 检查YAML格式是否正确,缩进是否一致 - - 确认修改的是用户配置文件(`config.user.yml`或`config/user/`目录),而非默认配置文件 + - 确认修改的是用户配置文件(`config/user/`目录),而非默认配置文件 - 运行`npm run dev`重新构建网站并查看 2. **图标不显示** @@ -615,7 +559,10 @@ notes: - 记住系统只会使用最高优先级的配置,不会合并不同配置 - 检查您是否在多个地方定义了相同的配置,造成覆盖 -> - 首次设置时,建议先复制一份完整默认配置,然后逐步修改 +> **📝 首次设置建议**: +> - 首先复制`config/_default/`目录中的文件到`config/user/`目录 +> - 然后逐步修改各配置文件,保持目录结构一致 +> - 使用文本编辑器时注意保持正确的YAML格式和缩进
@@ -630,11 +577,9 @@ MeNav支持从浏览器导入书签,快速批量添加网站链接,无需手 书签配置按以下优先级加载(从高到低): 1. `config/user/pages/bookmarks.yml` (模块化用户配置) -2. `bookmarks.user.yml`(双文件用户配置) -3. `config/_default/pages/bookmarks.yml` (模块化默认配置) -4. `bookmarks.yml`(双文件默认配置) +2. `config/_default/pages/bookmarks.yml` (模块化默认配置) -**注意:** 与主配置一样,书签配置采用完全替换策略,系统只会使用找到的最高优先级配置。 +**注意:** 书签配置采用完全替换策略,系统只会使用找到的最高优先级配置。 ### 导入步骤详解 @@ -680,7 +625,7 @@ MeNav支持从浏览器导入书签,快速批量添加网站链接,无需手 - 书签分类会变成网站分类 - 书签文件夹结构会被保留 - 系统自动尝试匹配网站图标 - - 生成的配置可在`bookmarks.user.yml`或`config/user/pages/bookmarks.yml`中查看和编辑 + - 生成的配置可在`config/user/pages/bookmarks.yml`中查看和编辑 ### 书签导入注意事项 @@ -693,13 +638,13 @@ MeNav支持从浏览器导入书签,快速批量添加网站链接,无需手 ## 常见问题
-为什么推荐使用模块化配置而非双文件配置? -模块化配置将不同功能的配置分散到多个文件中,便于管理和维护。当网站内容较多时,单一配置文件会变得臃肿难以编辑,而模块化配置则可以让您只关注需要修改的部分。 +模块化配置的优势是什么? +模块化配置将不同功能的配置分散到多个文件中,便于管理和维护。当网站内容较多时,分散的配置文件让您可以只关注需要修改的特定部分,避免配置文件变得臃肿难以编辑。
如何更改网站的主题或样式? -目前MeNav采用统一的设计风格,您可以通过修改`config/user/site.yml`(或`config.user.yml`)中的字体设置来调整网站外观。未来版本将考虑增加主题切换功能。 +目前MeNav采用统一的设计风格,您可以通过修改`config/user/site.yml`中的字体设置来调整网站外观。未来版本将考虑增加主题切换功能。
@@ -709,7 +654,31 @@ MeNav支持从浏览器导入书签,快速批量添加网站链接,无需手
导入的书签没有正确显示图标怎么办? -系统会尝试根据网址自动匹配Font Awesome图标。如果匹配不理想,您可以手动编辑`bookmarks.user.yml`或`config/user/pages/bookmarks.yml`,修改每个站点的icon属性。 +系统会尝试根据网址自动匹配Font Awesome图标。如果匹配不理想,您可以手动编辑`config/user/pages/bookmarks.yml`,修改每个站点的icon属性。 +
+ +
+如何从旧式配置迁移到模块化配置? + +由于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。
## 贡献指南