dove

一个用 Rust 生成静态网页的简洁导航站点生成器，输出可直接部署到 GitHub Pages / Cloudflare Pages / Cloudflare Workers。支持主题目录与模板引擎（Tera），可自定义 HTML/CSS/JS；支持内/外网两套页面；内置搜索引擎切换与两种布局（default/ntp）。

示例/模板配置仓库（可直接参考部署方式）：

dove-private：仅包含配置与 CI 的模板仓库（Pages/Workers 均支持）

环境要求：已安装 Rust 稳定版工具链（stable）。若在 CI 中构建，请在工作流中显式安装 Rust（推荐 dtolnay/rust-toolchain@stable）。

功能特性

配置拆分 include：主配置支持 include/includes，本地支持通配（glob），远程 URL（需 remote 特性）。
分类显示模式：每组可独立设置 display: standard|compact|list|text（支持中文别名）。
主题与模板：Tera 模板、多主题目录，静态资源可覆盖。
内/外网两套页面、跳转中间页（倒计时、UTM、风险等级）。
站点地图与 SEO：sitemap.xml、robots.txt、OG、canonical、基于 base_url。
离线支持：内置 Service Worker，首次访问后可离线使用。

快速开始

生成示例配置与默认主题：

cargo run -- init
根据配置生成静态站点到 dist/：

cargo run -- build

启动本地预览（默认监听 127.0.0.1:8787，启动前会先构建一次）：

cargo run -- preview --build-first

生成完成后，可直接访问 dist/（外网版）或 dist/intranet/（内网版）预览；若配置了 base_path，则页面位于 dist/<base_path>/ 下，或直接访问 /intranet/ 实现切换。页头可相互切换。

如需“本地仅保留模板、配置放在 Gist”：不放置 dove.yaml，用 --input-url 或环境变量 DOVE_INPUT_URL/DOVE_GIST_ID 指定远程配置。注意：远程加载功能位于可选特性 remote 中，默认未启用；请使用 --features remote。

命令一览（无需 Makefile）：

cargo run -- init 脚手架写出默认主题与示例配置
cargo run -- build 构建静态站点到 dist/
cargo run -- preview --build-first 本地预览并监听变更（默认 127.0.0.1:8787）

构建时下载远程图标（并发）

当以 --features remote 构建并执行 build/preview 时，程序会尝试在构建阶段并发下载配置中的远程图标（http/https 或 // 开头），保存为本地文件并在最终页面中优先引用本地文件；若下载失败，则继续使用原远程链接。

存放目录（相对站点根）：DOVE_ICON_DIR，默认 assets/icons
下载并发数：DOVE_ICON_THREADS，默认 8

说明：data: 内联图标与本地相对路径图标不会被下载。

配置说明（dove.yaml）

示例：

site:
  title: 我的导航站
  description: 常用站点与工具集合
  color_scheme: auto   # auto | light | dark
  theme_dir: themes/default
  base_path: secretPath   # 可选：将站点生成到 dist/secretPath/
  # 可选：站点基础 URL（用于 canonical、sitemap、OG 等绝对地址）
  base_url: https://nav.example.com
  # 可选：OG 分享图片；相对路径将在结合 base_url 后生成绝对地址
  og_image: assets/favicon.svg
  # 可选：首页布局（default | ntp）
  layout: ntp
  # 站点地图默认设置（可选）
  sitemap:
    default_changefreq: weekly   # always|hourly|daily|weekly|monthly|yearly|never
    default_priority: 0.5        # 0.0 - 1.0
    # lastmod: 2025-09-09        # 不设置则用构建时间
  # 搜索引擎（可选）
  search_engines:
    - name: Google
      template: https://www.google.com/search?q={q}
    - name: Bing
      template: https://www.bing.com/search?q={q}
  default_engine: Google
  redirect:               # 跳转页设置（仅外网链接生成中间页）
    delay_seconds: 3      # 自动跳转倒计时（秒），0 表示不自动跳转
    default_risk: low     # 默认风险等级：low|medium|high
    utm:                  # 站点级 UTM（可选；字段留空则不追加）
      source: nav
      medium: referral
      campaign: homepage

groups:
  - category: 常用
    name: 搜索
    links:
      - name: Google
        url: https://www.google.com
        intro: 搜索引擎        # 兼容旧字段名 desc
        # details: "<p>可选：富文本 HTML 详情</p>"
        icon: assets/favicon.svg
        intranet: http://google.corp   # 可选：内网地址
        risk: medium                   # 可选：覆盖默认风险等级
        utm:                           # 可选：覆盖站点级 UTM
          source: nav
          medium: card
          campaign: homepage
  - category: 开发
    name: 文档/学习
    links:
      - { name: MDN Web Docs, url: https://developer.mozilla.org, intro: Web 开发文档 }

site.color_scheme 控制颜色模式（自动/明亮/深色），也可在网页右上角按钮切换并记忆。
site.theme_dir 指向主题目录。主题目录需包含 templates/ 与 assets/。
site.base_path 可选：将站点输出到 dist/<base_path>/，部署后访问路径形如 https://domain/<base_path>/。
site.base_url、site.og_image 可选：用于 SEO/canonical/OG。未设置 base_url 时，sitemap 使用相对地址且 og_image 仅在为绝对地址时输出。
site.layout 可选：default|ntp，控制首页布局。
site.category_display 可选：按“分类名”控制显示样式，支持 standard|compact|list|text；另可用 site.default_category_display 设默认样式。
icon 可为相对路径或外链 URL。若不设置，也可不显示图标。
links[].intranet 可选，配置后会在“内网版页面”使用该地址；未配置时会回退到外网地址。
links[].intro 简介；兼容旧字段名 desc。links[].details 为可选富文本 HTML，仅在详情页展示；未设置时回退显示简介文本。
links[].intermediate_page 可选：布尔值，控制该链接是否生成跳转中间页；若设置则覆盖全局 generate_intermediate_page/DOVE_GENERATE_INTERMEDIATE_PAGE。
links[].slug 可选：显式指定外网中间页路径 go/<slug>/ 的目录名；若未指定，则：
- 默认用 name 生成 slug；
- 当同名重复时，重复项将改用 name+host 组合生成 slug；
- 若仍冲突，会在末尾追加 -2、-3 等序号确保唯一。
site.redirect 跳转页设置（仅外网模式生成）：
- delay_seconds 自动跳转倒计时；为 0 或缺省时不自动跳转。
- default_risk 默认风险等级（low|medium|high）。
- utm 站点级 UTM 参数（source/medium/campaign/term/content）。

注意：中间页的生成可以通过命令行参数 --generate-intermediate-page=false 或环境变量 DOVE_GENERATE_INTERMEDIATE_PAGE=false 来禁用。禁用后，链接默认直接跳转目标地址；如需为个别链接保留/关闭中间页，可在该链接上设置 intermediate_page: true|false 覆盖全局行为。

site.sitemap 站点地图默认设置：
- default_changefreq 默认变更频率：always|hourly|daily|weekly|monthly|yearly|never
- default_priority 默认优先级：0.0 - 1.0
- lastmod 站点级最近更新时间（不设置则用构建时间）
links[].lastmod、links[].changefreq、links[].priority：覆盖单个链接的站点地图字段。
links[].risk 可选：覆盖默认风险等级。
links[].utm 可选：覆盖站点级 UTM 参数。
site.search_engines 与 site.default_engine：配置搜索引擎列表及默认项；模板可使用 search_engines 与 engine_default 变量。

主题结构

templates/index.html.tera：首页模板（Tera）。可访问变量（常用）：
- site_title、site_desc、color_scheme（auto|light|dark）、layout
- mode（external|intranet）、mode_other_label（外网|内网）、network_switch_href、has_intranet
- categories：分类列表（侧边栏）
- groups：分组数组；每个分组包含 name、category 与 links
- links：每个链接包含 name、href、desc、icon、host
- search_engines、engine_default：搜索引擎选项与默认项
- meta_robots：内网页会注入 noindex,nofollow
- canonical_url、og_image：仅外网页面可用
templates/detail.html.tera：链接详情/跳转提示页（仅外网生成）。可访问变量：
- site_title、site_desc、color_scheme
- link_name、link_intro、link_details_html、link_icon、link_host、link_url
- risk_class（low|medium|high）、risk_label（低/中/高风险）
- has_delay（bool）、delay_seconds（数字）
assets/：静态资源（CSS/JS/图标等），会复制到输出目录的 assets/。

输出说明

站点根目录（若设置 base_path，在 dist/<base_path>/）
intranet/ 内网版导航（同上；若 --no-intranet 则不生成且页面不显示切换按钮）
go/<slug>/ 每个链接的详情/跳转提示页（仅外网版生成；导航页会将链接指向这些中间页；若 --generate-intermediate-page=false 则不生成且链接直接跳转目标地址）
sitemap.xml 站点地图：包含站点根路径与所有外网详情页（带 lastmod、changefreq、priority）。
robots.txt 基础抓取策略（默认 Allow: /）。
assets/sw.js Service Worker 文件，用于实现离线功能
assets/offline.html 离线页面，当用户离线时显示

离线功能

Dove 生成的网页支持离线使用。当用户首次访问网站时，Service Worker 会缓存所有必要的资源，包括：

HTML 文件（站点根与 go/ 子目录下的 index.html）
CSS 样式表（assets/styles.css）
JavaScript 脚本（assets/app.js, assets/qrcode.min.js）
图片资源（favicon 等）

当用户断网再次访问网站时，Service Worker 会提供缓存的内容，确保网站仍然可用。

如果需要自定义离线页面，可以修改主题目录中的 assets/offline.html 文件。

高级用法

cargo run --features remote -- build \
  --input-url https://gist.githubusercontent.com/<user>/<id>/raw/config.yaml \
  --out public --static-dir static --theme themes/default --base-path secretPath --no-intranet \
  --color-scheme dark --title "远程站点" --description "从远程加载"

# 预览更多参数
cargo run -- preview --addr 127.0.0.1:9090 --dir dist/secretPath
# 或基于远程配置推导目录（需启用 remote 特性）：
cargo run --features remote -- preview --build-first \
  --input-url https://gist.githubusercontent.com/<user>/<id>/raw/config.yaml \
  --color-scheme light --title "远程预览" --description "预览远程配置"

通过 Gist 加载配置（需启用 feature remote）：

# 使用 Gist（公开或私有）构建
cargo run --features remote -- build \
  --gist-id <GIST_ID> \
  --gist-file dove.yaml \  # 可选：不指定则取第一个文件
  --github-token <TOKEN> \  # 访问私有 Gist 时需要
  --auth-scheme Bearer \    # 授权方案，默认 token；也可用 Bearer
  --out public --static-dir static --theme themes/default --base-path secretPath --no-intranet \
  --color-scheme dark --title "Gist 站点" --description "从 Gist 加载"

# 使用 Gist 启动预览（启动前构建一次）
cargo run --features remote -- preview --build-first \
  --gist-id <GIST_ID> \
  --gist-file dove.yaml \  # 可选
  --github-token <TOKEN> \  # 私有 Gist 时必需
  --auth-scheme Bearer \    # 可选
  --color-scheme light --title "Gist 预览" --description "预览 Gist 配置"

说明：一旦指定了 --input-url 或 --gist-id，将忽略本地 --input 与自动发现的 dove.yaml，仅使用远程配置，并按 CLI/环境变量进行覆盖。

--input 指定配置文件（默认自动寻找 dove.yaml|dove.yml）。
--out 指定输出目录（默认 dist/）。
--static-dir 指定额外静态资源目录，递归拷贝到输出目录，可覆盖主题资源。
--theme 指定主题目录，优先级高于 site.theme_dir。
--base-path 指定站点根路径（相对子路径），优先级高于 site.base_path。
--no-intranet 仅生成外网版本页面（不生成 intranet/，且页面不显示切换按钮）。
--generate-intermediate-page 是否生成中间页（默认生成）。如果设置为 false，则链接直接跳转目标地址。
预览命令（preview）：
- --build-first 启动前先构建一次。
- --addr 监听地址（默认 127.0.0.1:8787）。
- --dir 指定服务目录（若未指定，将根据配置推导 dist/<base_path>）。
- --open 启动后自动在浏览器打开。

配置拆分与 include

当链接越来越多时，可以将 dove.yaml 拆分为多个片段文件，并在主配置中通过 include 引用：

# dove.yaml（主配置）
site:
  title: 我的导航站
  theme_dir: themes/default

# 引用片段（支持字符串或数组；顺序决定合并顺序）
include:
  - groups/common/*.yaml   # 本地通配（glob）
  - groups/dev.yaml        # 单个文件

# 也可继续在主文件里写 groups；主配置会覆盖 include 中的同名字段
groups:
  - { category: 顶部, name: 项目, links: [ { name: dove, url: https://github.com/dovenav/dove, intro: 站点生成器 } ] }

被包含的片段文件可以是：

一个完整或部分的配置映射（例如只包含 groups:、或 site: + search_engines:）；
或者直接是 “分组列表”的顶层序列（等价于写成 groups: [...]）。

合并规则（自上而下顺序）：

同名键为映射（mapping）时递归合并，后者覆盖前者；
同名键为序列（sequence）时拼接（例如 groups、search_engines）；
主配置文件中的字段优先级最高（覆盖 include 中同名字段）。

路径与范围：

本地 include 路径相对于主配置文件所在目录；支持通配符（*, ?, []）。
远程配置（--input-url 或 Gist，需启用 remote 特性）同样支持 include：
- 可写绝对 http(s):// 地址，或相对于主配置 URL 的相对路径；
- 远程 URL 不支持通配符。

循环引用会被检测并报错。

分类显示模式（per-group/per-category）

优先推荐在每个 group 下设置 display，也支持全局默认与按分类名映射（兼容用）：

取值：standard（标准卡片）、compact（简洁卡片）、list（列表项）、text（文本：标题 + 链接）。
优先级：groups[].display > site.category_display[分类名] > site.default_category_display（不填则为 standard）。
中文别名：标准/简洁/列表/文本。

示例（推荐：每组独立设置）：

site:
  title: 我的导航站
  theme_dir: themes/default
  default_category_display: standard  # 其他未配置的分组默认“标准”

groups:
  - category: a
    name: A-工具
    display: list   # 列表
    links:
      - { name: Google, url: https://www.google.com, intro: 搜索 }
  - category: b
    name: B-资源
    display: 文本   # 文本（标题 + 链接）
    links:
      - { name: GitHub, url: https://github.com, intro: 代码托管 }

说明：

标准（standard）：当前主题的卡片网格，显示图标、标题、简介。
简洁（compact）：更紧凑的卡片网格，不显示简介，只显示图标 + 标题。
列表（list）：每条作为列表项显示，标题在前，可附简介。
文本（text）：逐行显示“标题 · 链接文本”（点击仍会打开链接）。外网模式下如开启中间页，文本里显示的是目标站点链接。

高级/兼容：按分类名映射（不推荐）

保留 site.category_display 以兼容历史配置，按“分类名 -> 显示模式”映射；仅当未在分组设置 display 时才生效。

site:
  default_category_display: standard
  category_display:
    a: list
    b: text

groups:
  - category: a
    name: A-分组
    links: [ { name: Google, url: https://www.google.com, intro: 搜索 } ]
  - category: b
    name: B-分组
    links: [ { name: GitHub, url: https://github.com, intro: 代码托管 } ]

注意：若 groups[].display 已设置，则无论 site.category_display 如何配置，均以分组内设置为准（推荐做法）。

合并与优先级（重要）

同名键为“映射”（map，例如 site.title、site.redirect.default_risk）：主文件覆盖 include；递归合并。
同名键为“序列”（list，例如 groups、site.search_engines）：按顺序追加（不去重、不按 name 合并）。
合并顺序：先按 include 列表顺序合并所有被包含文件，再合并主文件内容；因此主文件优先级最高。
顺序效果：groups 等序列中，include 的条目会排在主文件前面。

示例

覆盖映射字段（主文件覆盖 include）

# include/a.yaml
site:
  title: 来自 include 的标题
  redirect:
    default_risk: medium

# dove.yaml（主文件）
include:
  - include/a.yaml
site:
  title: 主文件标题
  redirect:
    default_risk: low

# 结果：
# site.title = 主文件标题
# site.redirect.default_risk = low

追加序列字段（list 仅拼接不去重）

# include/a.yaml
site:
  search_engines:
    - { name: Google, template: https://www.google.com/search?q={q} }

# dove.yaml（主文件）
include:
  - include/a.yaml
site:
  search_engines:
    - { name: Bing, template: https://www.bing.com/search?q={q} }

# 结果顺序：site.search_engines = [ Google, Bing ]

groups 示例（序列，顺序追加）

# include/groups/common.yaml
groups:
  - { category: 常用, name: 搜索, links: [ { name: Google, url: https://www.google.com, intro: 搜索 } ] }

# dove.yaml（主文件）
include:
  - include/groups/common.yaml
groups:
  - { category: 置顶, name: 项目, links: [ { name: dove, url: https://github.com/dovenav/dove, intro: 站点生成器 } ] }

# 结果顺序：groups = [ 搜索(来自 include), 项目(主文件) ]
# 若主文件再写一个同名“搜索”分组，两者会并存，不会覆盖或按 name 合并。

include 文件顶层直接是序列（当作 groups 片段）

# include/dev.yaml（没有顶层键，直接是分组数组）
- { category: 开发, name: 平台, links: [ { name: GitHub, url: https://github.com, intro: 代码托管 } ] }

# dove.yaml（主文件）
include:
  - include/dev.yaml
groups:
  - { category: 置顶, name: 项目, links: [ { name: dove, url: https://github.com/dovenav/dove, intro: 站点生成器 } ] }

# 结果：include/dev.yaml 会作为 groups 片段加入 -> groups = [ 平台, 项目 ]

开发者指南

工程结构

本项目已将原本过长的 main.rs 按职责拆分为模块，便于维护与测试：

src/main.rs：程序入口，仅负责 clap 解析与命令分发。
src/cli.rs：CLI/子命令定义（clap 派生）。
src/commands.rs：命令调度与“有效参数”计算（CLI + 环境变量合并）。
src/config.rs：配置模型与加载（本地/URL/Gist），以及来源描述。
src/utils.rs：通用小工具（环境变量解析、安全子路径、URL 主机名等）。
src/build.rs：构建核心（拷贝资源、图标回写、Tera 渲染、robots/sitemap）。
src/icons.rs：远程图标规范化/并发下载与缓存（--features remote 时有效）。
src/init.rs：初始化脚手架（示例配置与内置默认主题写出）。
src/preview.rs：本地预览（文件监视 + 增量重建 + 热刷新 HTTP 服务）。

特性开关

remote（默认关闭）：
- 允许 --input-url 与 Gist 加载（--gist-id/--gist-file）；
- 构建阶段并发下载远程图标并本地缓存。
- 开启方式：cargo run --features remote -- build ...

模板上下文约定

首页模板 templates/index.html.tera 可访问（部分）：

站点信息：site_title、site_desc、color_scheme、layout
搜索引擎：search_engines、engine_default
列表数据：groups（含 name/category/links）、categories
其它：build_version、generate_intermediate_page、has_intranet
内/外网切换：network_switch_href、mode_other_label

详情页模板 templates/detail.html.tera 可访问：

link_name、link_intro、link_details_html、link_icon、link_host、link_url
风险与跳转：risk_class、risk_label、has_delay、delay_seconds

若新增模板变量，请在 src/build.rs 的渲染上下文中补充对应字段。

代码风格与约定

错误处理统一使用 anyhow::Result 与 Context 补充语境；避免 unwrap/expect。
遵循“模块内聚、函数精简”的拆分原则；公共 API 仅在需要时 pub(crate) 暴露。
环境变量解析集中在 src/utils.rs（env_opt_* 系列），避免分散解析逻辑。
路径组合使用 safe_subpath 过滤 ./.. 段，避免越界写入。
远程功能与并发下载需考虑在未启用 remote 特性时的降级路径（返回空映射、不报错）。
保持 CLI 兼容：模块重构不改变参数/帮助/默认行为。

本地开发与调试

编译：cargo build
运行：cargo run -- build / cargo run -- preview --build-first
远程功能：cargo run --features remote -- build --input-url <URL>
格式/静态检查（可选）：cargo fmt、cargo clippy -D warnings

Makefile 快捷命令

常用便捷命令（可配合 FEATURES="--features remote" 与 ARGS 使用）：

make build                 # cargo build $(FEATURES)
make build-remote          # cargo build --features remote
make build-site            # 运行生成：cargo run $(FEATURES) -- build $(ARGS)
make preview               # 预览：cargo run $(FEATURES) -- preview --build-first $(ARGS)
make preview-remote        # 启用 remote 特性预览
make init                  # 初始化示例与默认主题
make fmt                   # cargo fmt --all
make check-fmt             # cargo fmt --all -- --check
make clippy                # cargo clippy $(FEATURES) -- -D warnings
make lint                  # = check-fmt + clippy

PR 建议

尽量保持每个 PR 聚焦单一问题（如“新增模板变量 X”或“优化图标下载重试”）。
如涉及模板变量，请同步更新本 README 的“模板上下文约定”表述。
若修改 CLI 或环境变量行为，请在“CLI 参数与环境变量”章节对照更新说明。

禁用中间页示例

# 构建时不生成中间页，链接直接跳转到目标地址
cargo run -- build --generate-intermediate-page false

# 或使用环境变量
DOVE_GENERATE_INTERMEDIATE_PAGE=false cargo run -- build

# 预览时也可禁用中间页
cargo run -- preview --build-first --generate-intermediate-page false

初始化命令（init）：
- --force 强制覆盖已存在文件与主题。
- DIR 可选目标目录（默认当前目录）。

CLI 参数与环境变量

所有环境变量均有对应的 CLI 参数，便于在命令行直接覆盖：

常规：--input、--input-url、--out、--static-dir、--theme、--base-path、--no-intranet、（Preview）--addr
远程/Gist（需启用 --features remote）：--gist-id、--gist-file、--github-token、--auth-scheme
页面覆盖：--color-scheme（auto|light|dark）、--title、--description

优先级：CLI > 环境变量 > 配置文件 > 默认值。

来源选择：指定了 --input-url 或 --gist-id 时，将忽略本地 --input 与自动发现的 dove.yaml，仅读取远程配置并应用环境变量/CLI 覆盖。

环境变量清单（与上面 CLI 参数对应）：

DOVE_INPUT：配置文件路径（等价于 --input）
DOVE_INPUT_URL：配置文件 URL（等价于 --input-url，需启用 remote 特性）
DOVE_GIST_URL：配置文件 URL 的别名，指向 gist 的 raw 链接
DOVE_GIST_ID：配置所在 gist 的 ID（将通过 GitHub API 获取 raw_url）
DOVE_GIST_FILE：配合 DOVE_GIST_ID 指定文件名（不指定则取第一个文件）
DOVE_GITHUB_TOKEN：访问私有 Gist 时的 token（会作为 Authorization: token <TOKEN> 加到请求头）
DOVE_AUTH_SCHEME：可选，授权方案（默认 token，也可设为 Bearer 或其他值，最终头格式为 Authorization: <SCHEME> <TOKEN>）
DOVE_OUT：输出目录（等价于 --out）
DOVE_PREVIEW_ADDR：预览监听地址（等价于 --addr）
DOVE_STATIC：静态资源目录（等价于 --static-dir）
DOVE_THEME：主题目录（等价于 --theme）
DOVE_THEME_DIR：主题目录（DOVE_THEME 的别名）
DOVE_BASE_PATH：站点根路径（等价于 --base-path）
DOVE_NO_INTRANET：是否仅生成外网（真值如 1/true/yes/on 有效）
DOVE_GENERATE_INTERMEDIATE_PAGE：是否生成中间页（默认生成）。如果设置为 false，则链接直接跳转目标地址。
DOVE_COLOR_SCHEME：页面配色方案覆盖（auto|light|dark）
DOVE_TITLE：覆盖站点标题（仅影响渲染，不修改配置文件）
DOVE_DESCRIPTION：覆盖站点描述（仅影响渲染，不修改配置文件）

优先级：CLI > 环境变量 > 配置文件 > 默认值。

私有 Gist 建议：使用 DOVE_INPUT_URL 指向 Gist 的 raw 链接，或设置 DOVE_GIST_ID 并提供 DOVE_GITHUB_TOKEN（可配合 DOVE_AUTH_SCHEME=Bearer）；两种方式都会在请求中自动携带 Authorization 头。以上需启用 remote 特性。

版本信息（页脚）

本主题页脚默认显示构建版本与打包时间：… · v{{ build_version }} ({{ build_time }})。其中 build_version 在构建时注入，支持三种来源（按优先级）：

CLI 参数：--build-version <VER>（最高优先级）
环境变量：DOVE_BUILD_VERSION=<VER>
回退：crate 版本（CARGO_PKG_VERSION）

常用用法：

# 本地构建（推荐其一）
cargo run -- build --build-version "$(git describe --tags --always --dirty --long)"
# 或
DOVE_BUILD_VERSION="$(git describe --tags --always --dirty --long)" cargo run -- build

# 预览时也可带上版本（自动重建将沿用该值）
cargo run -- preview --build-first --build-version "$(git describe --tags --always --dirty --long)"

GitHub Actions（示例）：工作流中先计算版本，再通过 CLI 传递：

- name: Compute version
  id: ver
  run: echo "version=$(git describe --tags --always --dirty --long)" >> $GITHUB_OUTPUT
- name: Build
  run: cargo run -- build --build-version "${{ steps.ver.outputs.version }}"

说明：Actions 示例也同时设置了环境变量 DOVE_BUILD_VERSION（可选），但最终以 --build-version 为准；两者保持一致即可。

build_time 为构建开始时间（UTC，精确到秒，RFC3339 格式，如 2025-09-16T12:34:56Z），用于直观区分不同打包产物。

分类与分组（一级/二级）

一级分类：使用 groups[].category 字段；用于侧边栏分类列表（如“常用/开发/学习”）。未填写时默认归入“全部”。
二级分类（分组）：使用 groups[].name 字段；它是内容区中每个区块的标题。相同 category 的多个分组会归属到同一个一级分类下展示。
渲染规则：
- 仅当某分组内“有可展示链接”时，才会渲染该分组；
- 仅当至少有一个分组归属于某一级分类且该分组有可展示链接时，才会在侧边栏显示该一级分类；
- 外网页面只统计设置了 url 的链接；内网页面统计 intranet 或回退 url 的链接。
- 搜索时，仅显示包含匹配结果的分组；侧边栏仅显示仍有结果的一级分类。
- 当分类列表为空（无可展示分类）时，侧边栏不渲染（隐藏）。

示例：

groups:
  - category: 常用
    name: 搜索
    links:
      - { name: Google, url: https://www.google.com, intro: 搜索引擎 }
      - { name: Bing,   url: https://www.bing.com }

  - category: 常用
    name: 工具
    links:
      - { name: TinyPNG, url: https://tinypng.com }

  - category: 开发
    name: 文档/学习
    links:
      - { name: MDN, url: https://developer.mozilla.org }

说明：如果某个分组没有可展示的链接（例如外网模式下全部缺少 url），该分组与其所属分类不会出现在页面中。

部署到 GitHub Pages

你可以使用 GitHub Actions 将 dove 站点自动发布到 GitHub Pages。可直接参考示例仓库：dove-private（仅包含 dove.yaml 与工作流），按同样方式搭建你自己的“配置仓库”。

步骤摘要：

在你的配置仓库中添加工作流（.github/workflows/deploy.yml）：
- Checkout 配置仓库；
- Checkout 本项目 dovenav/dove 到子目录（例如 dove/）；
- 安装 Rust 工具链（如 dtolnay/rust-toolchain@stable）；
- 将 dove.yaml 拷贝到 dove/ 并执行 cargo run -- build；
- 使用 actions/configure-pages、actions/upload-pages-artifact、actions/deploy-pages 发布 dove/dist；
在仓库 Settings → Pages 中将 Source 设置为 “GitHub Actions”。
若为 Project Pages（https://<user>.github.io/<repo>/），建议在 dove.yaml 设置 site.base_path: <repo>；User/Org Pages 通常无需设置。

完整可用的工作流与详细说明见 dove-private/README.md。

部署到 Cloudflare Workers（可选）

也可以将 dove/dist 作为静态资源部署到 Cloudflare Workers，参考示例与说明见：

dove-private/README.md 中的 Workers 部署章节
示例工作流：dove-private/.github/workflows/deploy-worker.yml
配置：dove-private/wrangler.toml

部署到 Cloudflare Pages

推荐两种方式：

本地生成后上传

本地执行 cargo run -- build 生成 dist/。
在 Cloudflare Pages 新建项目，选择 “直接上传（Direct Upload）”，上传 dist/ 目录内容。

连接仓库并跳过构建

在 CI/CD 或本地生成 dist/ 并提交到仓库。
在 Cloudflare Pages 连接该仓库，Framework 选择 None。
Build command 留空或填 echo skip，Output directory 填 dist。

说明：Cloudflare Pages 默认并不会预装 Rust 工具链，不建议在 Pages 侧执行 cargo 构建。

程序预览

以下是程序界面的预览图：

许可

MIT

捐赠支持

如果这个项目对你有帮助，欢迎扫码打赏支持（感谢！）：

Name		Name	Last commit message	Last commit date
Latest commit History 101 Commits
.github/workflows		.github/workflows
src		src
themes/default		themes/default
.DS_Store		.DS_Store
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md

License

dovenav/dove

Folders and files

Latest commit

History

Repository files navigation