135 lines
5.6 KiB
Markdown
Executable File
135 lines
5.6 KiB
Markdown
Executable File
# MeNav 书签目录
|
||
|
||
## 目录
|
||
|
||
- [目录概述](#目录概述)
|
||
- [书签导入功能](#书签导入功能)
|
||
- [配置加载优先级（完全替换）](#配置加载优先级完全替换)
|
||
- [MarksVault 扩展集成](#marksvault-扩展集成)
|
||
- [书签导入流程](#书签导入流程)
|
||
- [确定性输出](#确定性输出)
|
||
- [支持的浏览器](#支持的浏览器)
|
||
- [书签格式要求](#书签格式要求)
|
||
- [文件处理机制](#文件处理机制)
|
||
|
||
## 目录概述
|
||
|
||
`bookmarks` 目录是 MeNav 项目中用于存放浏览器导出的书签文件的专用目录。该目录与书签导入功能直接关联，用于自动将浏览器书签转换为 MeNav 配置文件，从而快速生成个人导航站点。
|
||
|
||
## 书签导入功能
|
||
|
||
书签导入功能允许用户：
|
||
|
||
- 从浏览器导出书签为 HTML 文件
|
||
- 将书签文件放入此目录
|
||
- 通过自动处理将书签转换为网站配置
|
||
- 无需手动编辑即可批量导入网站链接
|
||
|
||
这一功能极大简化了网站内容的初始设置过程，特别适合需要迁移大量书签的用户。
|
||
|
||
## 配置加载优先级（完全替换）
|
||
|
||
书签页配置同样遵循项目的“完全替换”策略：系统只会选择一套配置目录加载，不会把 `user` 与 `_default` 混合合并。
|
||
|
||
- 若存在 `config/user/`：书签页配置应位于 `config/user/pages/bookmarks.yml`（通常由导入脚本生成）
|
||
- 否则：使用 `config/_default/pages/bookmarks.yml`（默认示例）
|
||
|
||
> 提示：一旦创建 `config/user/`，`config/_default/` 会被完全忽略，因此不要指望从默认配置“兜底补齐缺失项”。
|
||
|
||
## MarksVault 扩展集成
|
||
|
||
[MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展可与 MeNav 集成，实现书签自动同步：
|
||
|
||
- **一键推送书签**：扩展将书签 HTML 文件推送到仓库的 `bookmarks/` 目录
|
||
- **自动化处理**：GitHub Actions 检测到书签文件后自动运行导入脚本生成配置
|
||
- **自动清理**：处理完成后会删除已导入的 HTML 文件，避免重复处理
|
||
|
||
## 书签导入流程
|
||
|
||
完整的书签导入流程如下：
|
||
|
||
1. 在浏览器中导出书签为 HTML 文件
|
||
2. 将导出的书签文件放入 `bookmarks` 目录
|
||
3. 运行书签处理工具：
|
||
```bash
|
||
npm run import-bookmarks
|
||
```
|
||
- 若 `config/user/` 不存在，导入脚本会先从 `config/_default/` 初始化一份用户配置（因为配置采用“完全替换”策略，需要完整配置才能正常生成站点）。
|
||
（可选）若希望生成结果保持确定性（便于版本管理，减少时间戳导致的无意义 diff）：
|
||
```bash
|
||
MENAV_BOOKMARKS_DETERMINISTIC=1 npm run import-bookmarks
|
||
```
|
||
4. 系统自动解析书签文件内容
|
||
5. 根据书签文件夹结构生成分类
|
||
6. 生成配置文件保存到 `config/user/pages/bookmarks.yml`
|
||
7. 构建网站应用新配置：
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
> **重要说明**：在本地开发中，`npm run dev` 命令**不会**自动处理书签文件。您必须先手动运行 `npm run import-bookmarks` 命令处理书签，然后再运行 `npm run dev` 查看效果。这与 GitHub Actions 中的自动处理流程不同，请务必注意。
|
||
|
||
## 确定性输出
|
||
|
||
默认情况下，导入脚本会在生成的 `bookmarks.yml` 顶部写入时间戳注释，导致每次导入都会产生 diff。
|
||
|
||
若你希望生成结果尽量稳定（只有书签内容变化才产生 diff），可使用环境变量开启确定性输出：
|
||
|
||
```bash
|
||
MENAV_BOOKMARKS_DETERMINISTIC=1 npm run import-bookmarks
|
||
```
|
||
|
||
## 支持的浏览器
|
||
|
||
MeNav 书签导入功能支持从以下浏览器导出的书签文件：
|
||
|
||
- **Chrome** - 通过书签管理器导出
|
||
- **Firefox** - 通过书签库导出
|
||
- **Edge** - 通过收藏夹导出
|
||
- **Safari** - 通过书签菜单导出
|
||
- 其他支持标准 HTML 书签格式的浏览器
|
||
|
||
## 书签格式要求
|
||
|
||
导入的书签文件需满足以下要求：
|
||
|
||
- 文件格式：HTML（标准网络书签格式）
|
||
- 文件编码：UTF-8
|
||
- 文件结构：包含 `<DL>`、`<DT>` 和 `<A>` 标签的标准书签结构
|
||
- 文件大小：建议不超过 5MB（约数千个书签）
|
||
- 支持处理位于文件夹内的书签
|
||
- 支持处理不在任何文件夹内的根路径书签（自动归入"根目录书签"分类）
|
||
- 空文件夹会被忽略
|
||
|
||
## 文件处理机制
|
||
|
||
书签处理器 (`src/bookmark-processor.js`) 对书签文件进行以下处理：
|
||
|
||
1. **解析文件结构**：
|
||
- 读取书签 HTML 文件
|
||
- 解析 DOM 结构获取书签层次
|
||
- 提取文件夹和链接信息
|
||
|
||
2. **分类提取**：
|
||
- 将书签文件夹转换为网站分类
|
||
- 提取链接URL、标题和添加日期
|
||
|
||
3. **根路径书签处理**：
|
||
- **自动分类**：根路径书签会被自动归入名为"根目录书签"的特殊分类
|
||
- **显示位置**：该分类始终位于所有其他分类之前（第一位）
|
||
- **图标标识**：使用星标图标（fas fa-star）
|
||
- **条件生成**：只有存在根路径书签时才会创建该分类
|
||
- **自动映射**：根路径书签同样支持基于URL的自动图标映射功能
|
||
|
||
4. **图标分配**：
|
||
- 根据URL自动匹配合适的 Font Awesome 图标
|
||
- 为每个链接和分类分配图标
|
||
- 当 `icons.mode: favicon` 时，页面通常会优先显示站点 favicon；配置里的 `icon` 主要用于回退显示或在 `icons.mode: manual` 时使用（详见 `config/README.md`）
|
||
|
||
5. **配置生成**：
|
||
- 创建符合 MeNav 配置格式的 YAML 文件
|
||
- 按层级组织分类和链接
|
||
- 应用自动生成的元数据
|
||
|
||
将书签放入此目录后，您可以立即利用 MeNav 的书签处理功能，快速将书签转化为个性化导航站点。
|