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

快速开始

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

点击展开

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

克隆仓库

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

安装依赖

# 安装依赖
npm install

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

完成配置（见设置配置文件）
导入书签（可选）
- 将浏览器导出的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）

构建

# 启动开发服务器
npm run dev

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

# 生成静态HTML文件
npm run build

构建后的文件位于dist目录

提交前检查（推荐）

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

（可选）格式化代码：

npm run format

部署方式

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

快速部署到GitHub Pages（推荐）

点击展开

第一步：前置设置

Fork仓库:
- 点击右上角的 Fork 按钮复制此仓库到您的账号
启用Actions:
- 进入fork后的仓库
- 点击顶部的 "Actions" 标签页
- 点击绿色按钮 "I understand my workflows, go ahead and enable them"
配置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 部署（可选）

点击展开

MeNav 构建后是纯静态站点（dist/），仓库已内置 Docker 部署文件，可直接构建并运行。

方式一：Docker Compose（常用）

准备配置（首次使用）：
- 按设置配置文件完成 config/user/ 配置
- 如果要导入书签，可先把书签 HTML 放到 bookmarks/ 目录
构建并启动：

docker compose up -d --build

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

常用可选参数（通过环境变量传入）：

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

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

更新站点：
- 修改配置或内容后，重新执行 docker compose up -d --build

方式二：直接使用 Docker 命令

docker build -t menav \
  --build-arg MENAV_ENABLE_SYNC=false \
  --build-arg MENAV_IMPORT_BOOKMARKS=false .

docker run -d --name menav -p 8080:80 --restart unless-stopped menav

使用 GHCR 预构建镜像（免本地构建）

仓库已提供 Docker Publish (GHCR) 工作流（.github/workflows/docker-ghcr.yml）：

推送到 main 时自动发布 latest
推送 v* 标签时自动发布版本标签（如 v1.3.0）
对外标签策略：仅 latest 与版本标签

首次启用前请在仓库设置确认：

Settings -> Actions -> General -> Workflow permissions 设为 Read and write permissions
在 Packages 中将镜像可见性设为 Public（否则匿名用户无法拉取）

发布后，用户可直接拉取并运行（将 <owner>/<repo> 替换为你的仓库路径）：

docker run -d --name menav -p 8080:80 --restart unless-stopped ghcr.io/<owner>/<repo>:latest

部署到服务器

点击展开

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

构建静态网站:

npm run build

复制构建结果:
- 所有生成的静态文件都位于 dist 目录中
- 将 dist 目录中的所有文件复制到您的Web服务器根目录
配置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;
    }
}

更新配置:
- 如果您想在服务器上更新网站，只需重复上述步骤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 部署步骤：

进入仓库的 Settings -> Secrets and variables -> Actions
点击 "Variables" 标签页
点击 "New repository variable"
名称填写：ENABLE_GITHUB_PAGES
值填写：false
点击 "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/目录下创建并使用您自己的配置文件，不要直接修改默认配置文件，以便后续更新项目时不会丢失您的个性化设置。

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

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

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

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

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

书签导入功能

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

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

Star-History

Languages

JavaScript 65.7%

CSS 24.4%

Handlebars 9.6%

Shell 0.2%

Dockerfile 0.1%

README.md Unescape Escape

MeNav

预览

特点

技术栈

项目结构

文档导航

快速开始

部署方式

快速部署到GitHub Pages（推荐）

第一步：前置设置

第二步：自定义配置

第三步：等待自动部署

Docker 部署（可选）

方式一：Docker Compose（常用）

方式二：直接使用 Docker 命令

使用 GHCR 预构建镜像（免本地构建）

部署到服务器

其他CI/CD托管选项

设置配置文件

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

书签导入功能

Star-History

README.md