# <img src="assets/favicon.ico" width="48" style="vertical-align: middle;"> MeNav - 个人导航站

一键部署的静态个人导航站 | 自动化构建 | 支持书签导入

如果觉得项目有用，欢迎⭐Star/Fork支持，谢谢！

## 目录

- [在线预览](#在线预览)
- [功能特点](#功能特点)
- [近期更新](#近期更新)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [部署方式](#部署方式)
  - [快速部署到GitHub Pages](#快速部署到github-pages)
  - [部署到服务器](#部署到服务器)
- [设置配置文件](#设置配置文件)
  - [使用双文件配置](#使用双文件配置)
  - [使用模块化配置](#使用模块化配置)
- [书签导入功能](#书签导入功能)
- [贡献](#贡献)
- [许可证](#许可证)

## 在线预览

访问：[在线DEMO](https://rbetree.github.io/menav/)

## 功能特点

- 🎨 简洁美观的界面设计
- 📱 响应式布局，支持移动端
- 🔍 实时搜索功能
- 🎯 分类展示网站链接
- 👥 支持展示社交媒体链接
- 📝 支持多个内容页面（首页、项目、文章、友链）
- 📌 支持从浏览器导入书签
- 🧩 模块化配置/双文件配置
- 🔄 可部署到GitHub Pages或任何服务器

## 近期更新

<details>
<summary>点击查看/隐藏更新日志</summary>

### 2025/05/03

**1. 侧边栏收回功能**
- ✅ 添加侧边栏折叠/展开按钮，位于Logo文本右侧
- ✅ 侧边栏平滑折叠/展开过渡

**2. 移动端UI优化**
- ✅ 修复搜索按钮和侧边栏按钮遮挡问题
- ✅ 点击侧边栏导航项后自动收起侧边栏

**3. 配置加载优先级修复**
- ✅ 修复了模块化配置目录加载时的关键问题，确保site.yml中的fonts、profile和social配置正确应用
- ✅ 修复了home.yml中的categories配置未正确加载到导航首页的问题
- ✅ 增强了配置加载逻辑，确保按照优先级规则完整应用配置

### 2025/05/02

**1. 模块化配置**
- ✅ 支持将配置拆分为多个文件，便于管理和维护
- ✅ 引入配置目录结构，分离页面配置
- ✅ 保持向后兼容性，同时支持传统配置文件

### 2025/05/01

**1. 页面布局优化**
- ✅ 优化了内容区域和侧边栏的间距，确保各种分辨率下内容不会贴近边缘
- ✅ 卡片与边框始终保持合理间距，避免在窄屏设备上与滚动条贴边
- ✅ 调整了搜索结果区域的边距，与常规分类保持样式一致性

**2. 网站卡片文本优化**
- ✅ 为站点卡片标题添加单行文本截断，过长标题显示省略号
- ✅ 为站点描述添加两行限制和省略号，保持卡片布局整洁
- ✅ 添加卡片悬停提示，方便查看完整信息

**3. 移动端显示增强**
- ✅ 优化了移动端卡片尺寸，一屏可显示更多网址
- ✅ 图标大小自适应，在小屏幕上更加紧凑
- ✅ 为不同尺寸移动设备（768px、480px、400px）提供递进式UI优化
- ✅ 减小卡片内边距和元素间距，增加屏幕利用率

**4. 书签导入功能**
- ✅ 支持从Chrome、Firefox和Edge浏览器导入HTML格式书签
- ✅ 自动处理书签文件，解析文件夹结构和链接
- ✅ 智能匹配网站图标，根据URL自动分配合适的Font Awesome图标
- ✅ 生成配置文件，无需手动录入即可批量导入网站链接
- ✅ 与GitHub Actions集成，全自动化的导入和部署流程

</details>

## 技术栈

- HTML5 + CSS3
- JavaScript (原生)
- Font Awesome 图标
- GitHub Pages托管

## 项目结构

```
menav/
├── assets/           # 静态资源文件
│   ├── style.css     # 样式表
│   └── favicon.ico   # 网站图标
├── src/              # 源代码
│   ├── generator.js  # 静态网站生成器
│   └── script.js     # 前端JavaScript脚本
├── templates/        # HTML模板
│   └── index.html    # HTML骨架模板文件
├── dist/             # 生成的静态网站（由generator.js生成）
├── bookmarks/        # 书签导入目录
├── config/           # 模块化配置目录
│   ├── _default/     # 默认配置
│   │   ├── site.yml  # 网站基本配置
│   │   ├── navigation.yml # 导航配置
│   │   └── pages/    # 页面配置
│   │       ├── home.yml
│   │       ├── projects.yml
│   │       ├── articles.yml
│   │       ├── friends.yml
│   │       └── bookmarks.yml
│   └── user/         # 用户自定义配置
│       ├── site.yml  # 用户网站配置
│       ├── navigation.yml # 用户导航配置 
│       └── pages/    # 用户页面配置
├── config.yml        # 默认配置文件（传统格式）
└── config.user.yml   # 用户自定义配置文件（传统格式）
```

## 快速开始

1. 克隆仓库
```bash
git clone https://github.com/rbetree/menav.git
cd menav
```

2. 安装依赖
```bash
# 清理旧的依赖(如果需要)
rm -rf node_modules
rm -f package-lock.json

# 安装新的依赖
npm install
```

3. 修改配置
   - 可以选择使用双文件配置或模块化配置（见[设置配置文件](#设置配置文件)）
   - 自定义网站内容、导航链接、社交媒体链接等

4. 本地预览
```bash
npm run dev
```

## 部署方式

### 快速部署到GitHub Pages

#### 第一步：前置设置

1. Fork仓库:
   - 点击右上角的 Fork 按钮复制此仓库到您的账号

2. 启用必要功能:
   - 进入仓库的 Settings -> General
   - 找到 Features 部分
   - 勾选 "Issues"

3. 启用Actions:
   - 进入fork后的仓库
   - 点击顶部的 "Actions" 标签页
   - 点击绿色按钮 "I understand my workflows, go ahead and enable them"

4. 配置Pages:
   - 进入仓库的 Settings -> Pages
   - 在 "Build and deployment" 部分
   - Source: 选择 "GitHub Actions"

#### 第二步：自定义配置

1. 创建个人配置文件:
   - 可以使用双文件配置或模块化配置
   - 推荐使用模块化配置（见[使用模块化配置](#使用模块化配置)）
   - 提交您的配置文件到仓库

2. 等待自动部署:
   - GitHub Actions会自动检测您的更改
   - 构建并部署您的网站
   - 部署完成后，您可以在 Settings -> Pages 中找到您的网站地址

> 重要提示: 请注意不要在配置文件中包含敏感信息，因为它将被提交到公开仓库。

#### 故障排除

如果遇到部署问题:
1. 请确保完成了所有前置设置步骤
2. 检查每个设置页面是否都点击了 Save 按钮
3. 如果修改设置后部署仍然失败:
   - 进入 Actions 标签页
   - 找到失败的工作流
   - 点击 "Re-run all jobs" 重新运行

### 部署到服务器

如果您想部署到自己的Web服务器，只需要以下几个步骤：

1. 构建静态网站:
```bash
npm run build
```

2. 复制构建结果:
   - 所有生成的静态文件都位于 `dist` 目录中
   - 将 `dist` 目录中的所有文件复制到您的Web服务器根目录

3. 配置Web服务器:
   - 确保服务器配置为提供静态文件
   - 对于Apache: 在网站根目录中已有正确的 .htaccess 文件
   - 对于Nginx: 添加以下配置到您的server块:

```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /path/to/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}
```

4. 更新配置:
   - 如果您想在服务器上更新网站，只需重复上述步骤1-2
   - 或者设置自动部署流程，例如使用GitLab CI/CD或Jenkins

## 设置配置文件

MeNav支持两种配置方式：双文件配置和模块化配置（推荐）。

在加载配置时遵循以下优先级顺序：
1. `config/user/` （模块化用户配置）（优先级最高）
2. `config.user.yml`和 `bookmarks.user.yml`（双文件用户配置）
3. `config/_default/` （模块化默认配置）
4. `config.yml`和`bookmarks.yml`（双文件默认配置）（优先级最低）

**注意：** 各优先级配置间采用完全替换策略，而非合并。系统会选择存在的最高优先级配置，完全忽略其他低优先级配置。这确保了模块化配置和双文件配置都能独立使用，避免混合配置带来的意外行为。

### 使用双文件配置

双文件配置由 `config.yml`/`config.user.yml` 和 `bookmarks.yml`/`bookmarks.user.yml` 两个文件组成，适合小型网站和快速开始。

1. **创建配置文件**:
   - 复制 `config.yml` 为 `config.user.yml`
   - 对于书签配置，请勿手动创建 `bookmarks.user.yml`，它应通过[书签导入功能](#书签导入功能)自动生成
   - 编辑 `config.user.yml` 添加您的配置

2. **配置文件结构**:
```yaml
# 网站基本信息
site:
  title: 网站标题
  description: 网站描述
  author: 作者名
  favicon: favicon.ico  # 网站图标,支持ico、png等格式

# 字体设置
fonts:
  title:  # 标题字体
    family: 字体名称
    weight: 字重值
    source: 字体来源
  subtitle:  # 副标题字体
    family: 字体名称
    weight: 字重值
    source: 字体来源
  body:  # 正文字体
    family: 字体名称
    weight: 字重值
    source: 字体来源

# 个人信息
profile:
  title: 欢迎语
  subtitle: 副标题
  description: 描述

# 导航菜单
navigation:
  - name: 菜单名称
    icon: 图标类名
    id: 页面ID
    active: 是否激活

# 类别
categories:
  - name: 分类名称
    icon: 分类图标
    sites:
      - name: 网站名称
        url: 网站地址
        icon: 网站图标
        description: 网站描述

# 更多配置...
```

3. **添加网站链接**:
   在 `config.user.yml` 中的 categories 部分添加新站点：
```yaml
categories:
  - name: 分类名称
    icon: 分类图标
    sites:
      - name: 网站名称
        url: 网站地址
        icon: 网站图标
        description: 网站描述
```

4. **设置网站字体**:
   - `family`: 字体名称，支持Web安全字体或Google Fonts
   - `weight`: 字体粗细，常用值如400(常规)、500(中等)、600(粗体)等
   - `source`: 字体来源，可选"google"或"system"

   例如使用Google字体:
```yaml
fonts:
  body:
    family: "Noto Sans SC"  # Google提供的中文字体
    weight: 400
    source: "google"
```

5. **设置网站图标**:
   - 支持.ico、.png等格式
   - 建议尺寸为32x32或16x16像素
   - 将图标文件放在assets目录下
   - 在配置文件中设置：`favicon: favicon.ico`

### 使用模块化配置

模块化配置将配置分散到多个文件中，更易于管理和维护，推荐用于复杂网站。

#### 模块化配置目录结构

```
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    # 用户首页配置
        # 其他用户自定义页面...
```

#### 使用模块化配置的优势

1. **分离关注点**：每个页面和功能区域有专属配置文件
2. **简化编辑**：修改特定页面时只需编辑对应文件
3. **更好的版本控制**：减少合并冲突
4. **向后兼容**：仍然支持传统的 `config.yml` 和 `config.user.yml`


## 书签导入功能

MeNav支持从浏览器导入书签，快速批量添加网站链接。

在加载配置时遵循以下优先级顺序：

1. `config/user/pages/bookmarks.yml` （模块化用户配置）
2. `bookmarks.user.yml`（双文件用户配置的书签部分）
3. `config/_default/pages/bookmarks.yml` （模块化默认配置）
4. `bookmarks.yml`（双文件默认配置的书签部分）

**注意：** 与主配置一样，书签配置也采用完全替换策略，系统只会使用找到的最高优先级书签配置，完全忽略低优先级配置。

### 导入步骤

1. **从浏览器导出书签**
   - 在Chrome中: 打开书签管理器 -> 点击"更多"(三个点) -> 导出书签
   - 在Firefox中: 打开书签库 -> 显示所有书签 -> 导入和备份 -> 导出书签为HTML
   - 在Edge中: 设置 -> 收藏夹 -> 管理收藏夹 -> 导出为HTML文件

2. **导入书签到MeNav**
   - 在项目根目录下创建 `bookmarks` 文件夹(如果不存在)
   - 将导出的HTML书签文件放入 `bookmarks` 文件夹
   - 提交并推送变更到仓库
   - 系统会自动处理书签文件并生成配置文件

3. **书签处理结果**
   - 生成的书签配置会保存到 `bookmarks.user.yml`
   - 如果使用模块化配置，也会同时保存到 `config/user/pages/bookmarks.yml`
   - 自动开始构建

### 注意事项

- 仅支持标准HTML格式的书签文件
- 每次只会处理目录中最新的一个书签文件
- 处理完成后，书签文件会被自动清除，以防止重复处理

## 贡献

欢迎通过 Issues 或 Pull Requests 的形式做出贡献。如果您有好的想法或发现了问题，请随时提出。

## 许可证

AGPL-3.0 License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program requires that modified versions must also be made available under the same license when used over a network.