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

docs: 更新重构各readme文件

Browse Source
This commit is contained in:
rbetree
2025-12-22 01:45:58 +08:00
parent 47e4369b09
commit 2daba411ba
4 changed files with 150 additions and 359 deletions
Download Patch File Download Diff File Expand all files Collapse all files

373
README.md
View File

@@ -41,14 +41,13 @@
- [近期更新](#近期更新) - [近期更新](#近期更新)
- [技术栈](#技术栈) - [技术栈](#技术栈)
- [项目结构](#项目结构) - [项目结构](#项目结构)
- [文档导航](#文档导航)
- [快速开始](#快速开始) - [快速开始](#快速开始)
- [部署方式](#部署方式) - [部署方式](#部署方式)
- [部署到GitHub Pages](#快速部署到github-pages) - [部署到GitHub Pages](#快速部署到github-pages)
- [部署到自己的服务器](#部署到服务器) - [部署到自己的服务器](#部署到服务器)
- [其他CI/CD服务部署](#其他cicd托管选项) - [其他CI/CD服务部署](#其他cicd托管选项)
- [配置指南](#设置配置文件) - [配置指南](#设置配置文件)
- [使用配置](#使用配置)
- [配置详解](#配置详解)
- [书签导入](#书签导入功能) - [书签导入](#书签导入功能)
- [常见问题](#常见问题) - [常见问题](#常见问题)
- [Star-History](#Star-History) - [Star-History](#Star-History)
@@ -238,6 +237,15 @@ menav/
│ └── pages/ # 用户页面配置 │ └── pages/ # 用户页面配置
``` ```
## 文档导航
- 配置系统（完全替换策略、目录结构、示例）：[`config/README.md`](config/README.md)
- 书签导入（格式要求、流程、常见问题）：[`bookmarks/README.md`](bookmarks/README.md)
- 模板系统（组件、回退、数据流）：[`templates/README.md`](templates/README.md)
- 源码结构（各脚本职责）：[`src/README.md`](src/README.md)
- Handlebars helpers（模板辅助函数）：[`src/helpers/README.md`](src/helpers/README.md)
- 静态资源（样式/图片等）：[`assets/README.md`](assets/README.md)
## 快速开始 ## 快速开始
<details> <details>
@@ -257,7 +265,7 @@ cd menav
npm install npm install
``` ```
3. 完成配置（见[设置配置文件](##设置配置文件)） 3. 完成配置（见[设置配置文件](#设置配置文件)）
4. 导入书签（可选） 4. 导入书签（可选）
- 将浏览器导出的HTML格式书签文件放入`bookmarks`目录 - 将浏览器导出的HTML格式书签文件放入`bookmarks`目录
@@ -326,7 +334,7 @@ npm run format
创建个人配置文件: 创建个人配置文件:
- **重要:** 始终创建自己的用户配置文件，不要直接修改默认配置文件 - **重要:** 始终创建自己的用户配置文件，不要直接修改默认配置文件
- 完成配置文件（见[设置配置文件](##设置配置文件)） - 完成配置文件（见[设置配置文件](#设置配置文件)）
- 提交您的配置文件到仓库 - 提交您的配置文件到仓库
#### 第三步：等待自动部署 #### 第三步：等待自动部署
@@ -415,7 +423,9 @@ server {
## 设置配置文件 ## 设置配置文件
MeNav使用模块化配置方式，将配置分散到多个文件中，更易于管理和维护。 MeNav 使用模块化配置方式，将配置分散到多个 YAML 文件中，更易于管理和维护。
完整说明请直接看：[`config/README.md`](config/README.md)（以该文档为准）。
> **🔔 重要提示：** 请务必在`config/user/`目录下创建并使用您自己的配置文件，不要直接修改默认配置文件，以便后续更新项目时不会丢失您的个性化设置。 > **🔔 重要提示：** 请务必在`config/user/`目录下创建并使用您自己的配置文件，不要直接修改默认配置文件，以便后续更新项目时不会丢失您的个性化设置。
@@ -425,363 +435,22 @@ MeNav使用模块化配置方式，将配置分散到多个文件中，更易于
**注意：** 采用完全替换策略，而非合并。系统会选择存在的用户配置，完全忽略默认配置。 **注意：** 采用完全替换策略，而非合并。系统会选择存在的用户配置，完全忽略默认配置。
### 使用配置 ### 最小可用配置（快速指引）
* **创建配置目录**: - 首次使用建议先完整复制 `config/_default/` 到 `config/user/`，再按需修改（因为配置采用“完全替换”策略，不会从默认配置补齐缺失项）。
- 在`config/user/`目录下创建您的自定义配置文件 - 至少需要有 `config/user/site.yml`（缺失时构建会直接报错退出，避免生成空白站点）。
- 可以参考项目结构中的`config/_default/`目录结构
- 至少需要创建`site.yml`（缺失时构建会直接报错退出，避免生成空白站点）
- 首次使用建议先完整复制 `config/_default/` 到 `config/user/`，再按需修改（因为配置采用“完全替换”策略，不会从默认配置补齐缺失项）
### 配置详解
<details>
<summary>点击展开</summary>
MeNav的配置系统分为两个主要部分，对应两种不同类型的配置文件：
1. `site.yml` - 网站基本信息、字体、个人资料、社交媒体链接和导航菜单配置
2. `pages/` 目录 - 各页面的内容配置
以下详细介绍每个配置文件的结构和用途。
### 一、site.yml 配置文件
site.yml文件包含网站的基本信息、字体设置、个人资料、社交媒体链接和导航菜单等全局配置，这些设置会影响整个网站的呈现。
```yaml
# 网站基本信息
title: "我的导航站" # 网站标题，显示在浏览器标签和页面顶部
description: "个人网址导航" # 网站描述，用于SEO和分享卡片
author: "张三" # 作者姓名
favicon: "menav.svg" # 网站图标，支持ico、png等格式
logo_text: "导航站" # 左上角显示的Logo文本
icons:
mode: favicon # 可选: favicon | manual（默认 favicon）
# 字体设置
fonts:
title: # 标题字体设置
family: "Roboto" # 字体名称
weight: 700 # 字重值：400常规、500中等、700粗体
source: "google" # 字体来源：google或system
subtitle: # 副标题字体
family: "Noto Sans SC"
weight: 500
source: "google"
body: # 正文字体
family: "Noto Sans SC"
weight: 400
source: "google"
# 个人资料配置
profile:
title: "欢迎来到我的导航站" # 主标题/欢迎语
subtitle: "收集实用网站和工具" # 副标题
description: "这里整理了我日常使用的网站和工具，方便快速访问。" # 详细描述
# 社交媒体链接
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"
# 更多社交媒体...
```
#### 网站图标模式（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）。
```yaml
# 导航配置
navigation:
- name: "首页" # 菜单项名称
icon: "fas fa-home" # 菜单项图标
id: "home" # 页面标识符（必须唯一）
active: true # 是否默认激活（只能有一个为true）
- name: "项目"
icon: "fas fa-project-diagram"
id: "projects"
- name: "文章"
icon: "fas fa-book"
id: "articles"
# 更多导航项...
```
> **📝 温馨提示**：
> - 关于**字体设置**：
> - **system**表示使用系统自带字体，无需额外加载，页面加载速度更快
> - **google**表示从Google Fonts加载字体，选择更丰富，但可能影响加载速度
> - 中文网站推荐使用"Noto Sans SC"、"Source Han Sans CN"等支持中文的字体
> - 设置字重时请确保所选字体支持该字重值，否则可能无法正确显示
> - 关于**个人资料**：profile.description支持较长文本，可以添加一些个性化的介绍或使用说明，让您的导航站更具特色
> - 关于**社交媒体链接**：这些链接会显示在网站侧边栏的底部
> - 关于**导航配置**：
> - 每个导航项的`id`必须唯一，并且有对应的页面配置文件（该id必须与`pages/`文件夹中的页面配置文件名一致）
> - 只能设置一个导航项的`active`为`true`，作为默认显示页面
> - 图标使用Font Awesome 5图标库，格式为`前缀 fa-图标名`
> - 导航菜单的顺序与此配置中的顺序一致，可以通过调整项目顺序来更改导航顺序
### 二、pages目录 配置文件
pages目录包含每个页面的详细配置，每个文件对应一个页面。文件名必须与 `site.yml` 中 `navigation` 配置的 `id` 一致。
例如，对于导航中的"home"页面，需要创建`config/user/pages/home.yml`：
```yaml
# pages/home.yml示例
title: "我的主页" # 页面标题
subtitle: "常用网站导航" # 页面副标题
# 分类和网站配置
categories:
- name: "常用工具" # 分类名称
icon: "fas fa-tools" # 分类图标
sites: # 该分类下的网站列表
- name: "GitHub" # 网站名称
url: "https://github.com" # 网站链接
icon: "fab fa-github" # 网站图标
description: "全球最大的代码托管平台" # 网站描述
- name: "Google"
url: "https://google.com"
icon: "fab fa-google"
description: "全球最大的搜索引擎"
# 更多网站...
# 更多分类...
```
自定义页面配置示例（以"notes"为例）：
1. 首先在`site.yml`的`navigation`部分添加对应的导航项：
```yaml
# config/user/site.yml
navigation:
- 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编程技巧和案例"
# 更多网站...
```
#### 多层级嵌套配置
MeNav 支持多层级嵌套配置，允许创建更复杂的内容组织结构。特别适用于书签页面，可以创建分类 -> 子分类 -> 分组 -> 网站的多层结构。
##### 配置结构说明
多层级嵌套配置支持以下层级结构：
1. **二层级结构**（默认）：
```
分类 (categories)
└── 网站 (sites)
```
2. **三层级结构**：
```
分类 (categories)
└── 分组 (groups)
└── 网站 (sites)
```
3. **四层级结构**：
```
分类 (categories)
└── 子分类 (subcategories)
└── 分组 (groups)
└── 网站 (sites)
```
##### 四层级结构示例
```yaml
categories:
- name: "技术资源"
icon: "fas fa-laptop-code"
subcategories:
- name: "前端开发"
icon: "fas fa-code"
groups:
- name: "框架库"
icon: "fas fa-cube"
sites:
- name: "React"
url: "https://reactjs.org/"
icon: "fab fa-react"
description: "React官方文档"
- name: "Vue.js"
url: "https://vuejs.org/"
icon: "fab fa-vuejs"
description: "Vue.js官方文档"
- name: "状态管理"
icon: "fas fa-database"
sites:
- name: "Redux"
url: "https://redux.js.org/"
icon: "fas fa-database"
description: "Redux状态管理"
- name: "Vuex"
url: "https://vuex.vuejs.org/"
icon: "fas fa-database"
description: "Vue状态管理"
- name: "后端开发"
icon: "fas fa-server"
groups:
- name: "Node.js生态"
icon: "fab fa-node-js"
sites:
- name: "Express"
url: "https://expressjs.com/"
icon: "fas fa-server"
description: "Node.js Web框架"
- name: "Koa"
url: "https://koajs.com/"
icon: "fas fa-leaf"
description: "下一代Node.js框架"
```
### 向后兼容性
多层级嵌套配置完全向后兼容：
- 现有的二层级结构（categories -> sites）配置无需修改即可继续使用
- 系统会自动检测配置结构并应用相应的模板和样式
- 可以在同一配置中混合使用不同层级结构（某些分类使用二级结构，某些使用三级或四级结构）
- 模板系统会自动处理不同层级结构，无需手动指定模板类型
> **📝提示**：
> - 每个页面可以拥有不同的分类和网站
> - 网站描述建议简洁明了，不超过30个字符，以确保显示美观
> - 不同页面可以特化用于不同用途，如"工作"、"学习"、"娱乐"等
> - 页面数量不限，但建议控制在合理范围内，避免导航过长
### 三、配置文件结构示例
**完整配置结构**：
```
config/user/
├── site.yml # 网站基本信息、字体、个人资料、社交媒体链接和导航菜单配置
└── pages/
├── home.yml # 首页配置
├── projects.yml # 项目页配置
├── articles.yml # 文章页配置
├── friends.yml # 朋友页配置
└── notes.yml # 自定义笔记页配置
```
> **📝 首次设置建议**：
> - 首先复制`config/_default/`目录中的文件到`config/user/`目录
> - 然后逐步修改各配置文件，保持目录结构一致
> - 使用文本编辑器时注意保持正确的YAML格式和缩进
</details>
## 书签导入功能 ## 书签导入功能
MeNav支持从浏览器导入书签，快速批量添加网站链接，无需手动录入。 MeNav 支持从浏览器导入书签，快速批量添加网站链接；也支持与 MarksVault 扩展集成自动同步。
### MarksVault 浏览器扩展集成 完整说明请直接看：[`bookmarks/README.md`](bookmarks/README.md)（以该文档为准）。
[MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展提供与 MeNav 的无缝集成：
- **一键推送书签**：通过扩展直接将书签推送到您的 MeNav 项目
- **自动化处理**：推送的书签文件会被自动处理并转换为配置
- **自动删除**：处理完成后，原始书签文件会被自动删除，以防止重复处理
### 配置加载优先级
书签配置按以下优先级加载（从高到低）：
1. `config/user/pages/bookmarks.yml` （用户配置）
2. `config/_default/pages/bookmarks.yml` （默认配置）
**注意：** 书签配置采用完全替换策略，系统只会使用找到的最高优先级配置。
### 导入步骤详解
#### 使用 MarksVault 浏览器扩展（推荐）
- 安装 [MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展
- 在浏览器中登录并授权
- 使用扩展任务页中新建任务，将书签推送到您的 MeNav 项目
- 系统将自动处理并部署更新后的导航站
#### 手动导入
<details>
<summary>点击展开</summary>
1. **从浏览器导出html书签**
2. **导入书签到MeNav**
**GitHub Pages方式**:
- Fork本仓库后，在您的仓库中创建`bookmarks`目录
- 上传HTML格式书签文件到此目录
- GitHub Actions会自动处理文件并生成配置
**本地开发方式**:
- 在项目根目录创建`bookmarks`文件夹
- 复制HTML书签文件到此文件夹
- 运行`npm run import-bookmarks`命令处理书签文件
- 系统生成配置文件后即可使用`npm run dev`预览
#### 根路径书签处理
如果HTML书签文件中存在`不在任何文件夹内`的根路径书签，系统会：
- 自动创建名为"根目录书签"的特殊分类
- 该分类始终位于所有其他分类之前（第一位）
- 只有存在根路径书签时才会创建该分类
</details>
> 💡 *版本管理建议*：若你希望每次导入书签生成的 `bookmarks.yml` 内容保持确定性（避免因时间戳导致的无意义 diff），可在运行导入时设置环境变量：`MENAV_BOOKMARKS_DETERMINISTIC=1`。
> 生成的配置可在`config/user/pages/bookmarks.yml`中查看和编辑
## 常见问题 ## 常见问题
<details> <details>
<summary>如何自定义Handlebars模板？</summary> <summary>如何自定义Handlebars模板？</summary>
MeNav现在使用Handlebars模板系统，您可以通过以下步骤自定义模板： 模板系统完整说明请见：[`templates/README.md`](templates/README.md)。
1. **基本修改**：Fork项目后，您可以编辑`templates`目录下的模板文件
2. **结构说明**：
- `layouts`：包含整体页面布局模板
- `pages`：包含各页面的主要内容模板
- `components`：包含可复用的组件模板
3. **组件扩展**：创建新的组件模板时，需要在generator.js中注册，才能通过`{{> component-name}}`语法使用
4. **自定义页面**：新增页面需要在`templates/pages`添加模板，并确保有对应的配置文件
修改模板后，需要重新构建项目以应用更改。
</details> </details>
<details> <details>

39
bookmarks/README.md
View File

@@ -3,8 +3,11 @@
## 目录 ## 目录
- [目录概述](#目录概述) - [目录概述](#目录概述)
- [功能说明](#功能说明) - [书签导入功能](#书签导入功能)
- [配置加载优先级（完全替换）](#配置加载优先级完全替换)
- [MarksVault 扩展集成](#marksvault-扩展集成)
- [书签导入流程](#书签导入流程) - [书签导入流程](#书签导入流程)
- [确定性输出](#确定性输出)
- [支持的浏览器](#支持的浏览器) - [支持的浏览器](#支持的浏览器)
- [书签格式要求](#书签格式要求) - [书签格式要求](#书签格式要求)
- [文件处理机制](#文件处理机制) - [文件处理机制](#文件处理机制)
@@ -13,7 +16,7 @@
`bookmarks` 目录是 MeNav 项目中用于存放浏览器导出的书签文件的专用目录。该目录与书签导入功能直接关联，用于自动将浏览器书签转换为 MeNav 配置文件，从而快速生成个人导航站点。 `bookmarks` 目录是 MeNav 项目中用于存放浏览器导出的书签文件的专用目录。该目录与书签导入功能直接关联，用于自动将浏览器书签转换为 MeNav 配置文件，从而快速生成个人导航站点。
## 功能说明 ## 书签导入功能
书签导入功能允许用户： 书签导入功能允许用户：
@@ -24,6 +27,23 @@
这一功能极大简化了网站内容的初始设置过程，特别适合需要迁移大量书签的用户。 这一功能极大简化了网站内容的初始设置过程，特别适合需要迁移大量书签的用户。
## 配置加载优先级（完全替换）
书签页配置遵循项目的“完全替换”策略：系统只会使用找到的最高优先级配置，不会把默认配置与用户配置合并。
优先级（高 → 低）：
1. `config/user/pages/bookmarks.yml`（用户配置，通常由导入脚本生成）
2. `config/_default/pages/bookmarks.yml`（默认配置）
## MarksVault 扩展集成
[MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展可与 MeNav 集成，实现书签自动同步：
- **一键推送书签**：扩展将书签 HTML 文件推送到仓库的 `bookmarks/` 目录
- **自动化处理**：GitHub Actions 检测到书签文件后自动运行导入脚本生成配置
- **自动清理**：处理完成后会删除已导入的 HTML 文件，避免重复处理
## 书签导入流程 ## 书签导入流程
完整的书签导入流程如下： 完整的书签导入流程如下：
@@ -34,6 +54,10 @@
```bash ```bash
npm run import-bookmarks npm run import-bookmarks
``` ```
（可选）若希望生成结果保持确定性（便于版本管理，减少时间戳导致的无意义 diff）：
```bash
MENAV_BOOKMARKS_DETERMINISTIC=1 npm run import-bookmarks
```
4. 系统自动解析书签文件内容 4. 系统自动解析书签文件内容
5. 根据书签文件夹结构生成分类 5. 根据书签文件夹结构生成分类
6. 生成配置文件保存到 `config/user/pages/bookmarks.yml` 6. 生成配置文件保存到 `config/user/pages/bookmarks.yml`
@@ -44,6 +68,16 @@
> **重要说明**：在本地开发中，`npm run dev` 命令**不会**自动处理书签文件。您必须先手动运行 `npm run import-bookmarks` 命令处理书签，然后再运行 `npm run dev` 查看效果。这与 GitHub Actions 中的自动处理流程不同，请务必注意。 > **重要说明**：在本地开发中，`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 书签导入功能支持从以下浏览器导出的书签文件： MeNav 书签导入功能支持从以下浏览器导出的书签文件：
@@ -89,6 +123,7 @@ MeNav 书签导入功能支持从以下浏览器导出的书签文件：
4. **图标分配**： 4. **图标分配**：
- 根据URL自动匹配合适的 Font Awesome 图标 - 根据URL自动匹配合适的 Font Awesome 图标
- 为每个链接和分类分配图标 - 为每个链接和分类分配图标
- 当 `icons.mode: favicon` 时，页面通常会优先显示站点 favicon；配置里的 `icon` 主要用于回退显示或在 `icons.mode: manual` 时使用（详见 `config/README.md`）
5. **配置生成**： 5. **配置生成**：
- 创建符合 MeNav 配置格式的 YAML 文件 - 创建符合 MeNav 配置格式的 YAML 文件

89
config/README.md
View File

@@ -5,9 +5,14 @@
- [目录概述](#目录概述) - [目录概述](#目录概述)
- [配置目录结构](#配置目录结构) - [配置目录结构](#配置目录结构)
- [配置加载机制](#配置加载机制) - [配置加载机制](#配置加载机制)
- [推荐用法](#推荐用法)
- [模块化配置文件](#模块化配置文件) - [模块化配置文件](#模块化配置文件)
- [网站基础配置](#网站基础配置) - [网站基础配置](#网站基础配置)
- [页面配置](#页面配置) - [页面配置](#页面配置)
- [配置详解](#配置详解)
- [site.yml 常用字段](#siteyml-常用字段)
- [pages/ 页面配置](#pages-页面配置)
- [多层级嵌套配置（2-4层）](#多层级嵌套配置2-4层)
- [配置优先级](#配置优先级) - [配置优先级](#配置优先级)
- [配置示例](#配置示例) - [配置示例](#配置示例)
- [最佳实践](#最佳实践) - [最佳实践](#最佳实践)
@@ -46,6 +51,16 @@ MeNav 配置系统采用“完全替换”策略（不合并），按以下优
也就是说：`config/user/` 一旦存在，就需要包含一套完整的配置（例如 `site.yml` 与必要的 `pages/*.yml`），系统不会把缺失部分从默认配置补齐。 也就是说：`config/user/` 一旦存在，就需要包含一套完整的配置（例如 `site.yml` 与必要的 `pages/*.yml`），系统不会把缺失部分从默认配置补齐。
## 推荐用法
为避免文档与配置字段长期不同步，建议按以下方式使用与维护：
1. **首次使用**：完整复制 `config/_default/` 到 `config/user/`，再按需修改。
2. **字段与结构的权威参考**：
- 全局配置：[`_default/site.yml`](_default/site.yml)
- 页面配置：[`_default/pages/`](_default/pages/)
3. **多层级嵌套书签示例**：[`_default/pages/bookmarks-four-level.yml`](_default/pages/bookmarks-four-level.yml)（2~4 层结构均有覆盖）
## 模块化配置文件 ## 模块化配置文件
### 网站基础配置 ### 网站基础配置
@@ -72,6 +87,76 @@ MeNav 配置系统采用“完全替换”策略（不合并），按以下优
- `bookmarks.yml`: 书签页面配置 - `bookmarks.yml`: 书签页面配置
- 自定义页面配置 - 自定义页面配置
## 配置详解
本章节用于补齐“怎么配才是对的”这类细节说明。为了避免示例长期过时，字段与结构的权威参考始终以默认配置为准：
- 全局配置：[`_default/site.yml`](_default/site.yml)
- 页面配置：[`_default/pages/`](_default/pages/)
### site.yml 常用字段
`site.yml` 中字段较多，以下是常用项的解释与注意点（完整字段请以默认配置为准）：
1. **基础信息**
- `title`：站点标题
- `description`：站点描述（SEO/分享）
- `author`：作者/署名
- `favicon`、`logo_text`：站点图标与左上角 Logo 文本
2. **图标模式（隐私相关）**
- `icons.mode: favicon | manual`
- `favicon`：会请求第三方服务（Google）获取站点 favicon，失败自动回退到 Font Awesome 图标
- `manual`：完全使用手动 Font Awesome 图标，不发起外部请求（适合内网/离线/隐私敏感场景）
3. **字体**
- `fonts.*.source: google | system`
- `system`：使用系统字体，加载更快；`google`：可选字体更多但可能受网络影响
- 中文站点建议选择支持中文与字重的字体（如 `Noto Sans SC`）；请确保所选字体包含配置的字重，否则可能显示异常
4. **顶部欢迎信息与社交链接**
- `profile`：首页顶部欢迎信息
- `social`：侧边栏底部社交链接
- `profile.description` 可写较长文本，用于放置个性化介绍或使用说明
5. **导航**
- `navigation[]`：页面入口列表，`id` 需唯一，并与 `pages/` 中配置文件名对应（例如 `id: home` 对应 `pages/home.yml`）
- 只允许一个导航项 `active: true` 作为默认页
- 图标使用 Font Awesome 类名字符串（例如 `fas fa-home`、`fab fa-github`）
- 导航显示顺序与数组顺序一致，可通过调整数组顺序改变导航顺序
### pages/ 页面配置
页面配置位于 `pages/*.yml`，每个文件对应一个页面内容，文件名与导航 `id` 对应：
- `pages/home.yml`：首页（通常是 `categories -> sites`）
- `pages/projects.yml` / `articles.yml` / `friends.yml`：示例页面（可按需删改）
- `pages/bookmarks.yml`：书签页（通常由导入脚本生成，也可以手动维护）
> 提示：自定义页面时，先在 `site.yml` 的 `navigation` 中增加一个 `id`，再创建同名的 `pages/<id>.yml`。
>
> 站点描述建议简洁（例如不超过 30 个字符），以保证卡片展示更美观。
### 多层级嵌套配置（2-4层）
书签与分类支持 2~4 层嵌套，用于更好组织大量站点。建议直接参考默认示例：
- 四层结构示例：[`_default/pages/bookmarks-four-level.yml`](_default/pages/bookmarks-four-level.yml)
层级命名约定（自顶向下）：
1. `categories`：顶层分类
2. `subcategories`：子分类
3. `groups`：分组
4. `subgroups`：子分组
5. `sites`：站点（叶子节点）
#### 向后兼容性
- 原有二层结构（`categories -> sites`）无需修改即可继续使用
- 系统会自动识别层级结构并匹配对应的模板/样式
- 允许在同一份配置中混用不同层级（例如某些分类是二层，某些分类是三/四层）
## 配置优先级 ## 配置优先级
配置项的优先级从高到低为： 配置项的优先级从高到低为：
@@ -172,6 +257,6 @@ categories:
- 定期备份您的用户配置 - 定期备份您的用户配置
4. **配置验证**: 4. **配置验证**:
- 修改配置后先在本地构建测试 - 修改配置后运行 `npm run check`（语法检查 + 单测 + 构建）
- 使用 `npm run dev` 预览更改效果 - 需要本地预览时运行 `npm run dev`（命令入口见 [`../README.md#快速开始`](../README.md#快速开始)）
- 确保 YAML 语法正确无误 - 确保 YAML 语法正确无误

4
templates/README.md
View File

@@ -299,7 +299,9 @@ categories:
{{/if}} {{/if}}
``` ```
提示：关于 `icons.mode` 与隐私说明，请参见 README 的“网站图标模式（icons.mode）”章节与“近期更新”。 提示：关于 `icons.mode` 的配置与隐私说明，请参见：
- `config/README.md` 的 `site.yml 常用字段`：[`../config/README.md#siteyml-常用字段`](../config/README.md#siteyml-%E5%B8%B8%E7%94%A8%E5%AD%97%E6%AE%B5)
- 根目录 `README.md` 的“近期更新”：[`../README.md#近期更新`](../README.md#%E8%BF%91%E6%9C%9F%E6%9B%B4%E6%96%B0)
## 模板数据流 ## 模板数据流