嵌入式搜索

官方主题 youlog 集成 Algolia{target="_blank"} 全文搜索。效果可参考 youlog 演示站{target="_blank"}。

推荐流程：在 everkm.yaml 配置 config.algolia 并设 push_on_export: true → everkm-publish serve --export（导出成功后自动 reset → push）→ 预览/部署静态站。

需要单独控制推送节奏、或 CI 中关闭自动推送时，使用 everkm-publish algolia（读 everkm.yaml，不要求 push_on_export: true，无需重复填写索引名等参数）。

1. 准备 Algolia

Application ID
Admin API Key（推送索引用，勿提交到仓库）
Search-Only API Key（前端搜索用，可写入 everkm.yaml）

2. 配置 `everkm.yaml`

在 __everkm/everkm.yaml 的 config 下配置 algolia（推荐）：

config:
  algolia:
    push_on_export: true

    app_id: YOUR_APP_ID
    api_key: YOUR_SEARCH_ONLY_API_KEY   # 前端用，可暴露
    admin_key: ~                        # 推送用；留空则读环境变量 ALGOLIA_ADMIN_KEY
    index_name: my-index
    site: my-site-id                    # 站点标识（多站共用索引时区分不同站）
    channel: main                       # 栏目标识（同站多栏目独立推送时区分）

    url_base: https://your-domain.com/  # 导出后 push 拼页面绝对 URL
    body_selector: "#article-main"      # 正文 CSS 选择器，默认 .markdown-body
    languages:                          # reset 时写入 Algolia indexLanguages（ISO 639-1）
      - zh
      - en

字段	说明
`push_on_export`	`true` 时导出完成后自动推送；`false` 或未配置则跳过
`app_id`	Application ID
`api_key`	Search-Only API Key，写入模板 `__config` 供前端搜索
`admin_key`	Admin API Key；可省略，改由 `ALGOLIA_ADMIN_KEY` 环境变量提供
`index_name`	索引名；多语言可用翻译对象（见多语言）
`site`	站点标识：多个站共用同一 Algolia 索引时，用于区分不同站点的数据
`channel`	栏目标识：同一站点内多个子栏目独立导出、独立推送时，用于区分各栏目的数据
`url_base`	须带 `https://`，建议尾部 `/`
`body_selector`	从导出 HTML 抽取正文的 CSS 选择器，需与主题 DOM 一致
`languages`	Algolia `indexLanguages` / `queryLanguages`，须为 ISO 639-1（如 `zh`、`en`）；与站内 i18n 的 `zh_CN` 等不同，但写 `zh_CN` 会在推送时自动转为 `zh`

`site` 与 `channel`

二者为独立的过滤维度，互不绑定：

场景	建议配置
多站共用索引	为每个站配置不同的 `site`
同站多栏目分别维护	每次推送配置对应的 `channel`（单栏目站可固定如 `main`）
前端全文搜索	通常只按 `site` 过滤，即可搜索该站全部栏目
重建索引（`reset`）	配置了 `site` 和/或 `channel` 中的哪一项，就只清理该项对应范围的旧数据；两项都未配置时才清空整个索引

多站共用索引时，reset 请至少指定 site，避免仅按 channel 清理时误伤其他站点下同名栏目。

兼容：未配置 algolia 时，仍读取历史字段 algolia_search（youlog 旧名），行为相同。

保存后重启预览；顶栏搜索框需主题已构建搜索插件资源。

3. 导出并自动推送

export ALGOLIA_ADMIN_KEY="你的 Admin API Key"   # 未写 admin_key 时必填

everkm-publish serve --export

导出成功且 config.algolia.push_on_export: true、凭证齐全时，会自动 reset → push 推送 dist/。推送失败不会导致导出失败，请查看日志。

本地开发若暂不需要推送，将 push_on_export: false 或去掉 algolia 配置即可。

单页推送失败（如网络超时）时，失败记录会写入 __everkm/cache/algolia-push-failed.json（含页面 URL 与 dist 内 HTML 路径）。可执行：

everkm-publish algolia ./my-site retry-failed

逐条重推缓存中的页面；成功则从文件中移除，全部成功后删除缓存文件，失败则更新错误信息。

4. 手动推送（`everkm-publish algolia`）

索引推送能力已内置于 everkm-publish algolia，从站点 everkm.yaml 读取 config.algolia，无需单独安装其它工具或重复填写 --index-name 等参数。

export ALGOLIA_ADMIN_KEY="你的 Admin API Key"   # 未写 admin_key 时必填

everkm-publish algolia ./my-site reset
everkm-publish algolia ./my-site push
everkm-publish algolia ./my-site retry-failed

子命令	说明
`reset`	按已配置的 `site` 和/或 `channel` 清理旧文档（有则附加、全无则清空整个索引），并写入索引设置
`push`	仅从 `dist/` 推送（不含 reset）
`retry-failed`	重推 `algolia-push-failed.json` 中的失败页；全部成功后删除缓存文件

reset 与 push 相互独立；完整手动推送需先 reset 再 push（与导出自动推送的 reset → push 一致）。

可选：--lang、--dist-dir、--config（与 serve 一致）。

youlog 多站场景：各站 config.algolia.site 应配置为不同标识。

更多主题侧字段见 theme-youlog{target="_blank"}。

关于 `ekmp-algolia`

早期曾提供独立的 ekmp-algolia npm CLI；该工具已停止更新，推送逻辑已稳定合并进 everkm-publish algolia。新站点请统一使用上文命令；既有 CI 若仍调用 ekmp-algolia，建议改为 everkm-publish algolia。

5. CI 示例

密钥通过 CI 环境变量注入，勿写入仓库。以下 方式 A / B 二选一（勿在 push_on_export: true 时再用方式 B，否则会重复推送）：

export ALGOLIA_ADMIN_KEY="$ALGOLIA_ADMIN_KEY"

# 方式 A：everkm.yaml 中 push_on_export: true + 索引参数齐全 → 导出后自动 reset → push
everkm-publish serve --export

# 方式 B：push_on_export: false 或未配置时，导出后手动两步（与 §4 相同）
everkm-publish serve --export
everkm-publish algolia ./my-site reset
everkm-publish algolia ./my-site push

1. 准备 Algolia

2. 配置 everkm.yaml

site 与 channel