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

feat(readme): 更新文档和配置注释

Browse Source
This commit is contained in:
coolzr
2025-10-19 00:24:03 +08:00
parent aa264cc727
commit 9e2a8b0da4
10 changed files with 221 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
README.md
View File

@@ -75,6 +75,49 @@
<details>
<summary>点击查看/隐藏更新日志</summary>
### 2025/10/18
**1. 图标模式默认行为变更**
- ✅ 默认启用 `icons.mode: favicon`，自动根据站点 URL 加载 favicon（失败回退为 Font Awesome 图标）
- ℹ️ 如需关闭外部请求并完全使用手动图标，请在 `config/user/site.yml` 中设置：
```yaml
# config/user/site.yml
icons:
mode: manual # 关闭 favicon 请求，纯手动图标
```
**ℹ️ 隐私说明（Favicon API）**
- 使用 `https://t3.gstatic.com/faviconV2` 服务会将站点 `URL` 发送至第三方（Google）以获取 favicon 图片
- 若不希望产生外部网络请求或在内网/离线环境中部署，请设置 `icons.mode: manual`
### 2025/10/14
**1. 拼音搜索支持**
- ✅ 支持中文拼音与首字母匹配检索（基于 `pinyin-match`）
### 2025/07/30
**1. 链接打开行为一致性**
- ✅ 统一站点/导航外链为新标签页打开，改善导航体验
### 2025/07/07
**1. UI 细节优化**
- ✅ 侧边栏显示与布局细节优化
- ✅ 明暗主题切换按钮样式改进
- ✅ 欢迎文本与布局对齐优化
### 2025/05/22
**1. MeNav 浏览器扩展支持接口**
- ✅ 注入序列化的配置数据供扩展读取（`configJSON`）
- ✅ 暴露 `window.MeNav` 基础能力与 DOM 数据属性，支持元素精准定位与更新
- ✅ 为扩展推送与页面联动打通基础能力
### 2025/05/16
**1. MarksVault 浏览器扩展集成**
@@ -142,7 +185,7 @@
**4. 书签导入功能**
- ✅ 支持从Chrome、Firefox和Edge浏览器导入HTML格式书签
- ✅ 自动处理书签文件，解析文件夹结构和链接
- ✅ 智能匹配网站图标，根据URL自动分配合适的Font Awesome图标
- ✅ 图标处理：默认加载站点 favicon；在 manual 模式下保留 Font Awesome 匹配
- ✅ 生成配置文件，无需手动录入即可批量导入网站链接
- ✅ 与GitHub Actions集成，全自动化的导入和部署流程
@@ -153,7 +196,7 @@
- HTML5 + CSS3
- JavaScript (原生)
- Handlebars 模板引擎
- Font Awesome 图标
- Font Awesome 图标 + Google Favicon API
- GitHub Pages托管/其他各种CI/CD服务托管
## 项目结构
@@ -417,6 +460,9 @@ author: "张三" # 作者姓名
favicon: "favicon.ico" # 网站图标，支持ico、png等格式
logo_text: "导航站" # 左上角显示的Logo文本
icons:
mode: favicon # 可选: favicon | manual（默认 favicon）
# 字体设置
fonts:
title: # 标题字体设置
@@ -449,6 +495,20 @@ social:
# 更多社交媒体...
```
#### 网站图标模式（icons.mode）
支持两种站点卡片图标模式，默认使用 favicon API：
- mode=favicon：使用 Google Favicon API 加载站点图标；加载失败时回退为 Font Awesome 的 `fas fa-link`；图标图片使用 `loading="lazy"` 延迟加载以提升首页性能。
- mode=manual：沿用手动指定的 Font Awesome 图标，不发起任何 favicon 请求。
所用 Favicon API：
`https://t3.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url={{url}}&size=32`
隐私说明：
- 启用 `mode=favicon` 时，页面会请求第三方服务以获取图片，可能将站点 `URL` 发送至该服务商（Google）。
> **📝 温馨提示**：
> - 关于**字体设置**：
> - **system**表示使用系统自带字体，无需额外加载，页面加载速度更快
@@ -724,7 +784,19 @@ MeNav现在使用Handlebars模板系统，您可以通过以下步骤自定义
<details>
<summary>导入的书签没有正确显示图标怎么办？</summary>
系统会尝试根据网址自动匹配Font Awesome图标。如果匹配不理想，您可以手动编辑`config/user/pages/bookmarks.yml`，修改每个站点的icon属性。
默认启用 favicon 模式：页面会尝试从第三方服务获取站点 favicon；若 URL 不是 http/https、站点无 favicon 或网络受限，将自动回退为 Font Awesome 图标。
如果您希望完全关闭外部请求并手动控制图标：
关闭 favicon 模式：
```yaml
# config/user/site.yml
icons:
mode: manual # 全局不再请求 favicon，仅使用 Font Awesome 图标
```
提示：更改配置后重新构建即可生效。
</details>
<details>
@@ -765,4 +837,4 @@ MarksVault浏览器扩展与MeNav的集成相当简单：
## Star-History
[![Star History Chart](https://api.star-history.com/svg?repos=rbetree/menav&type=Date)](https://www.star-history.com/#rbetree/menav&Date)
[![Star History Chart](https://api.star-history.com/svg?repos=rbetree/menav&type=Date)](https://www.star-history.com/#rbetree/menav&Date)

15
config/_default/navigation.yml
View File

@@ -1,7 +1,12 @@
- name: 首页
icon: fas fa-home
id: home
active: true
# 默认导航配置（请勿直接修改）。
# 建议复制到 config/user/navigation.yml 并按需调整。
# 规则：
# - 每个导航项的 id 必须唯一，并与 pages/<id>.yml 对应
# - 全局仅允许一个 active: true 作为默认激活页面
- name: 首页 # 菜单名称
icon: fas fa-home # Font Awesome 图标类
id: home # 页面标识符（唯一，需与 pages/home.yml 对应）
active: true # 是否默认激活（全局仅一个 true）
- name: 项目
icon: fas fa-project-diagram
id: projects
@@ -13,4 +18,4 @@
id: friends
- name: 书签
icon: fas fa-bookmark
id: bookmarks
id: bookmarks

21
config/_default/pages/articles.yml
View File

@@ -1,17 +1,20 @@
title: 技术文章
subtitle: 分享我的技术文章和学习笔记
# 默认页面配置（请勿直接修改）。
# 建议复制到 config/user/pages/articles.yml 并按需调整。
title: 技术文章 # 页面标题
subtitle: 分享我的技术文章和学习笔记 # 页面副标题
# 指定使用的模板文件名，现有页面模板可见templates\pages
# 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
template: articles
# 页面分类与站点列表
categories:
- name: 最新文章
icon: fas fa-pen
icon: fas fa-pen # 分类图标
sites:
- name: Vue3最佳实践
icon: fab fa-vuejs
description: Vue3组合式API的使用技巧
url: "#"
- name: Vue3最佳实践 # 站点名称
icon: fab fa-vuejs # 文章/站点图标
description: Vue3组合式API的使用技巧 # 摘要
url: "#" # 链接（示例）
- name: JavaScript进阶
icon: fab fa-js
description: JavaScript高级特性解析
@@ -34,4 +37,4 @@ categories:
- name: Node.js实战
icon: fab fa-node-js
description: Node.js服务端开发笔记
url: "#"
url: "#"

18
config/_default/pages/bookmarks.yml
View File

@@ -1,17 +1,21 @@
# 默认页面配置（请勿直接修改）。
# 建议复制到 config/user/pages/bookmarks.yml 并按需调整。
# 说明：该页面通常由“书签导入工具”自动生成，手工修改时请保持字段结构一致。
title: 我的书签
subtitle: 从浏览器导入的书签收藏
# 指定使用的模板文件名，现有页面模板可见templates\pages
# 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
template: bookmarks
# 页面分类与站点列表（大量示例项，按需删减）
categories:
- name: 技术资源
icon: fas fa-folder
icon: fas fa-folder # 分类图标
sites:
- name: GitHub
url: https://github.com/
icon: fab fa-github
description: "从书签导入: GitHub"
- name: GitHub # 站点名称
url: https://github.com/ # http/https URL（favicon 模式将尝试加载站点图标）
icon: fab fa-github # 手动图标（manual 模式显示；favicon 失败时回退）
description: "从书签导入: GitHub" # 描述
- name: Stack Overflow
url: https://stackoverflow.com/
icon: fab fa-stack-overflow
@@ -30,4 +34,4 @@ categories:
- name: LinkedIn
url: https://www.linkedin.com/
icon: fab fa-linkedin
description: "从书签导入: LinkedIn"
description: "从书签导入: LinkedIn"

21
config/_default/pages/friends.yml
View File

@@ -1,17 +1,20 @@
title: 友情链接
subtitle: 优秀的博主和朋友们
# 默认页面配置（请勿直接修改）。
# 建议复制到 config/user/pages/friends.yml 并按需调整。
title: 友情链接 # 页面标题
subtitle: 优秀的博主和朋友们 # 页面副标题
# 指定使用的模板文件名，现有页面模板可见templates\pages
# 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
template: friends
# 页面分类与站点列表
categories:
- name: 技术博主
icon: fas fa-user-friends
icon: fas fa-user-friends # 分类图标
sites:
- name: 小明的博客
icon: fas fa-code
description: 全栈开发工程师，分享技术心得
url: "#"
- name: 小明的博客 # 站点名称
icon: fas fa-code # 站点图标
description: 全栈开发工程师，分享技术心得 # 描述
url: "#" # 链接（示例）
- name: 小红的前端
icon: fas fa-paint-brush
description: 专注前端开发与设计
@@ -30,4 +33,4 @@ categories:
- name: Stack Overflow
icon: fab fa-stack-overflow
description: 程序员问答社区
url: https://stackoverflow.com
url: https://stackoverflow.com

21
config/_default/pages/home.yml
View File

@@ -1,17 +1,20 @@
title: 欢迎使用
subtitle: 个人导航站点
# 默认页面配置（请勿直接修改）。
# 建议复制到 config/user/pages/home.yml 并按需调整。
title: 欢迎使用 # 页面标题
subtitle: 个人导航站点 # 页面副标题
# 指定使用的模板文件名，现有页面模板可见templates\pages
# 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
template: home
# 页面分类与站点列表（可按需增删顺序）
categories:
- name: 常用网站
icon: fas fa-star
icon: fas fa-star # 分类图标（Font Awesome）
sites:
- name: Linux.do
url: https://linux.do/
icon: fab fa-linux
description: 新的理想型社区
- name: Linux.do # 站点名称
url: https://linux.do/ # http/https URL（favicon 模式将尝试加载站点图标）
icon: fab fa-linux # 手动图标：manual 模式使用；favicon 模式下作为回退
description: 新的理想型社区 # 站点描述
- name: Google
url: https://www.google.com
icon: fab fa-google
@@ -214,4 +217,4 @@ categories:
- name: Heroku
url: https://www.heroku.com
icon: fas fa-h-square
description: 应用部署平台
description: 应用部署平台

21
config/_default/pages/projects.yml
View File

@@ -1,17 +1,20 @@
title: 我的项目
subtitle: 这里展示了我的一些个人项目和开源贡献
# 默认页面配置（请勿直接修改）。
# 建议复制到 config/user/pages/projects.yml 并按需调整。
title: 我的项目 # 页面标题
subtitle: 这里展示了我的一些个人项目和开源贡献 # 页面副标题
# 指定使用的模板文件名，现有页面模板可见templates\pages
# 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
template: projects
# 页面分类与站点列表
categories:
- name: 个人项目
icon: fas fa-code
icon: fas fa-code # 分类图标（Font Awesome）
sites:
- name: 个人导航站
icon: fas fa-compass
description: 一个简洁美观的个人导航页面
url: "#"
- name: 个人导航站 # 站点名称
icon: fas fa-compass # 手动图标（manual 模式显示；favicon 模式下作为回退）
description: 一个简洁美观的个人导航页面 # 站点描述
url: "#" # 链接（示例）
- name: Todo List
icon: fas fa-tasks
description: 基于Vue3的待办事项管理器
@@ -30,4 +33,4 @@ categories:
- name: Project B
icon: fab fa-github
description: 开源项目贡献
url: "#"
url: "#"

16
config/_default/site.yml
View File

@@ -1,9 +1,21 @@
# 默认配置（请勿直接修改）。
# 建议复制到 config/user/site.yml 并按需调整；用户配置采用“完全替换”策略，将覆盖默认配置。
# 网站基本信息
title: 我的导航
description: 个人网络导航站
author: Your Name
favicon: favicon.ico
logo_text: 导航站
icons:
# 站点卡片图标模式：
# - favicon：自动根据 URL 加载站点 favicon（失败时回退到 Font Awesome 图标）
# - manual：始终使用手动指定的 Font Awesome 图标（不发起外部请求）
# 隐私提示：启用 favicon 模式会请求第三方服务以获取图标，可能将站点 URL 发送给服务商（详见 README“隐私说明”）。
mode: favicon # 可选: favicon | manual（默认 favicon）
# 字体设置（source: google | system；请确保字体支持相应字重）
fonts:
title:
family: Poppins
@@ -18,11 +30,13 @@ fonts:
weight: 400
source: google
# 个人资料：显示在首页顶部的欢迎信息
profile:
title: Hello,
subtitle: Welcome to My Navigation
description: 导航菜单
# 社交媒体链接：显示在侧边栏底部；可按需增删
social:
- name: GitHub
url: https://github.com
@@ -35,4 +49,4 @@ social:
icon: fab fa-twitter
- name: Steam
url: https://steam.com
icon: fab fa-steam
icon: fab fa-steam

24
src/helpers/README.md
View File

@@ -50,6 +50,19 @@ MeNav 的助手函数分为四类：
- 空值检查
- 逻辑运算（与、或、非）
#### ifHttpUrl
判断字符串是否为 http/https URL，用于在模板中分支渲染仅对外链生效的逻辑（如 favicon 加载）：
```handlebars
{{#ifHttpUrl url}}
{{!-- 只有 http/https 才尝试加载 favicon --}}
<img src="https://t3.gstatic.com/faviconV2?url={{encodeURIComponent url}}&size=32" alt="{{name}} favicon" />
{{else}}
<i class="fas fa-link"></i>
{{/ifHttpUrl}}
```
### 工具函数
位置：`src/helpers/utils.js`
@@ -61,6 +74,15 @@ MeNav 的助手函数分为四类：
- 范围数组生成
- 对象属性选择
#### encodeURIComponent
对字符串进行 URL 组件编码（同名于浏览器 API，用作模板内联助手），适用于将动态 URL 参数安全拼接到查询串：
```handlebars
{{!-- 构造第三方 Favicon API 的 url 参数 --}}
<img src="https://t3.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&url={{encodeURIComponent url}}&size=32" alt="favicon" />
```
### 核心函数
位置：`src/helpers/index.js`
@@ -379,4 +401,4 @@ function registerAllHelpers(handlebars) {
4. **避免副作用** - 助手函数应为纯函数，不修改传入的数据
5. **保持简单** - 每个助手函数应只完成一个明确的任务
5. **保持简单** - 每个助手函数应只完成一个明确的任务

38
templates/README.md
View File

@@ -128,6 +128,44 @@ templates/
{{/if}}
```
### 站点图标渲染（favicon/manual）
当启用 `icons.mode: favicon`（默认）时，站点卡片会优先显示站点 favicon；当 URL 非 http/https、加载失败或网络受限，则自动回退到 Font Awesome 图标。相关助手：`ifHttpUrl`（条件）与 `encodeURIComponent`（工具）。
示例（与内置组件实现保持一致）：
```handlebars
{{#if url}}
<a href="{{url}}" class="site-card" title="{{name}} - {{#if description}}{{description}}{{else}}{{url}}{{/if}}" {{#if external}}target="_blank" rel="noopener"{{/if}}>
{{#ifEquals @root.icons.mode "favicon"}}
{{#ifHttpUrl url}}
<i class="fas fa-circle-notch fa-spin icon-placeholder" aria-hidden="true"></i>
<img
class="favicon-icon"
src="https://t3.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url={{encodeURIComponent url}}&size=32"
alt="{{name}} favicon"
loading="lazy"
{{!-- 可选：降低引用者信息外泄 --}}
{{!-- referrerpolicy="no-referrer" --}}
style="opacity:0;"
onload="this.style.opacity='1'; this.previousElementSibling.style.display='none';"
onerror="this.style.display='none'; this.previousElementSibling.style.display='none'; this.nextElementSibling.style.display='inline-block';"
/>
<i class="fas fa-link icon-fallback" aria-hidden="true" style="display:none;"></i>
{{else}}
<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}}"></i>
{{/ifHttpUrl}}
{{else}}
<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}}"></i>
{{/ifEquals}}
<h3>{{#if name}}{{name}}{{else}}未命名站点{{/if}}</h3>
<p>{{#if description}}{{description}}{{else}}{{url}}{{/if}}</p>
</a>
{{/if}}
```
提示：关于 `icons.mode` 与隐私说明，请参见 README 的“网站图标模式（icons.mode）”章节与“近期更新”。
## 模板数据流
MeNav 模板系统的数据流如下：