MeNav

一个轻量的个人导航网站

📋 静态一键部署 | ⚡ 自动化构建 | 🔖 支持书签导入

MeNav 是一个轻量级、高度可定制的个人导航网站生成器，让您轻松创建属于自己的导航主页。无需数据库和后端服务，完全静态部署，支持一键 Fork 部署到 GitHub Pages，还可以从浏览器书签一键导入网站。配合 MarksVault 浏览器扩展，更支持书签自动同步和导航站自动更新。

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

直接开始部署>>

预览

在线访问

特点

• 简洁美观的响应式布局设计
• 集成外部搜索引擎
• 分类展示网站链接
• 模块化配置
• 支持从浏览器导入书签
• 支持2-4层级的多层级嵌套结构
• 与 MarksVault 浏览器扩展集成，支持自动推送书签
• 可部署到GitHub Pages或任何类似的CI/CD服务

历史更新记录已迁移至 CHANGELOG.md，README 不再维护该部分。

技术栈

• HTML5 + CSS3
• JavaScript (原生)
• Handlebars 模板引擎
• Google Favicon API + Font Awesome 图标

项目结构

menav/
├── src/        # 生成器、书签处理、前端脚本（入口：src/generator.js）
├── templates/  # Handlebars 模板（layouts/pages/components）
├── config/     # 模块化配置
├── assets/     # 静态资源
├── bookmarks/  # 书签导入相关
└── dist/       # 构建产物

文档导航

• 历史更新记录（README 不再维护）：CHANGELOG.md
• 更新说明2025/12/27（兼容性移除 / 迁移指南）：config/update-instructions-20251227.md
• 配置系统（完全替换策略、目录结构、示例）：config/README.md
• 书签导入（格式要求、流程、常见问题）：bookmarks/README.md
• 模板系统（组件、回退、数据流）：templates/README.md
• 源码结构（各脚本职责）：src/README.md
• Handlebars helpers（模板辅助函数）：src/helpers/README.md
• 静态资源（样式/图片等）：assets/README.md

快速开始

用于本地开发预览与构建静态站点；在线部署见 部署方式。

点击展开

通过以下步骤快速设置您的个人导航站：

1. 克隆仓库

git clone https://github.com/rbetree/menav.git
cd menav

2. 安装依赖

# 安装依赖
npm install

（本仓库的 GitHub Actions/CI 已改为使用 npm ci，以获得更稳定、可复现的依赖安装（基于 package-lock.json）；本地开发可继续使用 npm install，也可直接使用 npm ci。）

3. 完成配置（见设置配置文件）

4. 导入书签（可选）

   • 将浏览器导出的HTML格式书签文件放入bookmarks目录
   • 运行书签处理命令：

   npm run import-bookmarks

   • 若希望生成结果保持确定性（便于版本管理，减少时间戳导致的无意义 diff）：

   MENAV_BOOKMARKS_DETERMINISTIC=1 npm run import-bookmarks

   • 系统会自动将书签转换为配置文件保存到config/user/pages/bookmarks.yml

• 注意：npm run dev命令不会自动处理书签文件，必须先手动运行上述命令
• npm run dev 默认会刷新 articles/projects 的联网缓存（若你希望离线启动，请使用 npm run dev:offline）

5. 构建

# 启动开发服务器
npm run dev

# 离线启动开发服务器（不刷新联网缓存）
npm run dev:offline

# 生成静态HTML文件
npm run build

构建后的文件位于dist目录

6. 提交前检查（推荐）

# 一键检查（语法检查 + 单元测试 + 构建）
npm run check

（可选）格式化代码：

npm run format

部署方式

用于将生成的静态站点发布到 服务器 or CI/CD；本地构建见 快速开始。

快速部署到GitHub Pages（推荐）

点击展开

第一步：前置设置

1. Fork仓库:

   • 点击右上角的 Fork 按钮复制此仓库到您的账号

2. 启用Actions:

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

3. 配置Pages:

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

第二步：自定义配置

创建个人配置文件:

• 重要: 始终创建自己的用户配置文件，不要直接修改默认配置文件
• 完成配置文件（见设置配置文件）
• 提交您的配置文件到仓库

第三步：等待自动部署

• GitHub Actions会自动检测您的更改
• 构建并部署您的网站
• 部署完成后，您可以在 Settings -> Pages 中找到您的网站地址
  • 站点内容的“时效性数据”（RSS 文章聚合、projects 仓库统计）会由部署工作流在构建前自动刷新
  • 也支持定时刷新：默认每天 UTC 02:00 触发一次（GitHub Actions cron 使用 UTC；北京时间=UTC+8，可在 .github/workflows/deploy.yml 中调整 schedule.cron）

重要: Sync fork后需要手动触发工作流:

• 当您使用GitHub界面上的"Sync fork"按钮同步本仓库的更新后
• GitHub Actions工作流不会自动运行
• 您需要手动触发构建流程:
  • 进入 Actions 标签页
  • 选择左侧的 "Build and Deploy" 工作流
  • 点击 "Run workflow" 按钮

Docker 部署（可选）

点击展开

仓库已内置 docker-compose.yml，并提供 GHCR 预构建镜像；两种方式都建议统一使用 Docker Compose。

说明：容器每次启动都会在容器内执行 npm run build 生成 dist/，然后用 nginx 提供静态文件。

请在仓库根目录执行（需要 config/_default 等文件）。

方式 A：使用预构建镜像（推荐，免本地构建）

docker compose pull
docker compose up -d --no-build

方式 B：本地构建镜像（适合二次开发/改源码）

docker compose up -d --build

默认访问地址：http://localhost:8080

可选参数（环境变量）

MENAV_PORT=80 MENAV_ENABLE_SYNC=true MENAV_IMPORT_BOOKMARKS=true docker compose up -d --no-build

• MENAV_PORT：宿主机端口（默认 8080）
• MENAV_ENABLE_SYNC：启动构建时是否联网执行 sync-*（默认 false，更稳定）
• MENAV_IMPORT_BOOKMARKS：启动构建前是否执行 npm run import-bookmarks（默认 false）

配置与更新

• 配置目录挂载在 ./config，个人配置按“完全替换策略”建议：将 config/_default/ 完整复制到 config/user/ 再修改（见 设置配置文件 与 config/README.md）。
• 如需导入书签：将浏览器导出的书签 HTML 放到 ./bookmarks/，并设置 MENAV_IMPORT_BOOKMARKS=true 后重启容器。
• 修改配置/书签后生效方式（触发重新构建）：

docker compose restart menav

部署到服务器

点击展开

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

1. 构建静态网站:

npm run build

2. 复制构建结果:

   • 所有生成的静态文件都位于 dist 目录中
   • 将 dist 目录中的所有文件复制到您的Web服务器根目录

3. 配置Web服务器:

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

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

    location / {
        try_files $uri $uri/ /404.html;
    }
}

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

其他CI/CD托管选项

点击展开

除了GitHub Pages外，您还可以使用其他各种CI/CD服务部署MeNav：

如 Vercel / Netlify / Cloudflare Pages:

• 连接您的GitHub仓库
• 设置构建命令为npm run build
• 设置输出目录为dist

如果您只使用第三方平台部署（不使用 GitHub Pages）：

为避免 GitHub Actions 中的 Pages 配置错误，您可以禁用 GitHub Pages 部署步骤：

1. 进入仓库的 Settings -> Secrets and variables -> Actions
2. 点击 "Variables" 标签页
3. 点击 "New repository variable"
4. 名称填写：ENABLE_GITHUB_PAGES
5. 值填写：false
6. 点击 "Add variable"

设置后，GitHub Actions 仍会自动构建网站（包括书签处理、RSS 同步等），但会跳过 GitHub Pages 部署步骤，避免报错。第三方平台（如 Vercel/Cloudflare Pages）会自动检测到代码变化并部署。

如果你希望在构建时刷新“时效性数据”（RSS 文章聚合、projects 仓库统计），请将构建命令改为：

npm ci && npm run sync-projects && npm run sync-articles && npm run build

说明：sync-* 会联网抓取并写入 dev/ 缓存（仓库默认 gitignore）；同步脚本为 best-effort，失败不会阻断后续 build。

备注：dev/ 只用于构建过程的中间缓存，默认不会被提交到仓库；部署时也只会上传 dist/，不会包含 dev/。

书签转换依赖 GitHub Actions 如果需要使用书签自动推送功能，必须先在 GitHub 仓库中启用 GitHub Actions

部署流程：

1. 上传书签 → 2. GitHub Actions 处理 → 3. 使用处理完成的代码在 GitHub Pages 自动部署
                           ↓
          4. 其他 CI/CD 托管平台检测到变化 → 5. 使用处理完成的代码自动部署

无论选择哪种部署方式，请确保创建并使用您自己的配置文件，而不是直接修改默认配置。

设置配置文件

MeNav 使用模块化配置方式，将配置分散到多个 YAML 文件中，更易于管理和维护。

完整说明请直接看：config/README.md（以该文档为准）。

🔔 重要提示： 请务必在config/user/目录下创建并使用您自己的配置文件，不要直接修改默认配置文件，以便后续更新项目时不会丢失您的个性化设置。

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

1. config/user/ （用户配置）（优先级最高）
2. config/_default/ （默认配置）

注意： 采用完全替换策略，而非合并。系统会选择存在的用户配置，完全忽略默认配置。

最小可用配置（快速指引）

• 首次使用建议先完整复制 config/_default/ 到 config/user/，再按需修改（因为配置采用“完全替换”策略，不会从默认配置补齐缺失项）。
• 至少需要有 config/user/site.yml（缺失时构建会直接报错退出，避免生成空白站点）。

书签导入功能

MeNav 支持从浏览器导入书签，快速批量添加网站链接；也支持与 MarksVault 扩展集成自动同步。

完整说明请直接看：bookmarks/README.md（以该文档为准）。

Star-History