Antora 整合 Lunr

写于 2021-01-17

Lunr 是一个纯前端的全文搜索组件。

Antora 下对应的索引生成器是 antora-lunr ，以及整合好的全站生成器 antora-site-generator-lunr 。

  • 工作原理

    1. Antora 生成站点时，同时生成全站全文索引 search-index.js，作为静态文件一同发布。

    2. 用户在搜索框键入关键字时，search.js 调用 lunr.js 完成对索引的检索。

  • 优点

    • 简单，整合度高。

    • 可用于内网环境。

  • 缺点

    • 用户需要下载整个索引文件，占用带宽／流量。

    • 对大量页面（> 1000）建立索引、进行检索时性能较差。

    • 不支持中文。有社区方案，但未整合进上游。

  • 替代方案

    • 使用外部引擎 Algolia DocSearch

    • 使用搜索引擎 site: 关键字（古典方案）

我简单尝试了一下 antora-site-generator-lunr，放到了本站中。本文记录下流程。

流程

  1. 添加 UI

  2. 使用生成器

需要环境：

  • Node.js

预计耗时：10 分钟

添加 UI - 懒人方案

直接用 我整合好的 UI 包 ，在自己 Antora 项目的 antora-playbook.yml 中指定即可。

antora-playbook.yml
ui:
  bundle:
    url: https://gitlab.com/yanwk/antora-ui-yanwk/-/jobs/artifacts/yanwk/download?job=bundle-dev
    snapshot: true

添加 UI - 自助方案

从 antora-lunr 的样例 中复制出来文件，放到自己 Antora 项目的 supplemental-ui 目录下，不要忘了在 antora-playbook.yml 中指定 supplemental_files 。

antora-playbook.yml
# UI设置
ui:
  bundle:
    url: ./ui-bundle.zip
    snapshot: true # snapshot 告诉生成器这是个会更新的文件，每次都要重新获取。
    # start_path: dir1 # 指定子目录，此处不需要
  supplemental_files: ./supplemental-ui # 指定UI包以外的附加文件
  # default_layout: base # 指定 layout，默认 default
  # output_dir: _/dir1 # 生成站点时，UI 目录放在哪儿
附加文件与原文件是覆盖关系，注意对照检查。
可以参考 docs.antora.org 的搜索框样式

使用生成器

运行命令：

# 更新 antora-site-generator-lunr，必须使用卸载-重装的方式
npm uninstall -g \
antora-site-generator-lunr \
@antora/cli \
@antora/site-generator-default

npm install -g \
antora-site-generator-lunr \
@antora/cli \
@antora/site-generator-default

# 启用 lunr 搜索并生成站点，且只索引文档的最新版本
DOCSEARCH_ENABLED=true \
DOCSEARCH_ENGINE=lunr \
DOCSEARCH_INDEX_VERSION=latest \
DOCSEARCH_LANGS=en,zh \
NODE_PATH="$(npm -g root)" \
antora --generator antora-site-generator-lunr antora-playbook.yml

目前 Lunr 只支持英文搜索，但是上述命令中预留了 zh 参数（不会报错）。

有时间再试着折腾下中文搜索吧。