全文检索
OINK 的搜索是本地搜索:Hugo 在构建时给每种语言生成一份 JSON 索引,读者的浏览器下载它,在本地完成检索。不需要爬虫、账号、CDN,也不需要联网。主题默认不启用,一行配置即可开启。
搜索的入口是命令面板,打开方式与面板的其余内容见命令面板。
打开本地搜索
这一个键决定索引、Lunr 运行时与搜索对话框是否进入页面。三个条件同时成立时页面才带上它们:
params.offline_search为真;- 页面是首页,或者用了外壳布局(
docs/book/blog/swagger,见布局与页面类型),或者是开着params.ui.landing_search的落地页; - 当前输出不是打印。
任何一条不成立,构建就不往这个页面里放对话框、索引引用与 Lunr。这些资源不是被隐藏,而是不生成。
hugo server 下索引默认 也会生成,预览行为与线上一致。站点极大、每次改动都重建全站索引明显拖慢预览时,把它关掉:
控制索引体积
offline_search_index 决定每个页面往索引里写多少内容,因此同时决定两件事:读者能否搜到正文里的词,以及第一次搜索要下载多大的文件。
| 取值 | 索引进去的内容 | 什么时候用 |
|---|---|---|
title |
标题、标签、分类、search_keywords |
只靠标题定位的超大站 |
heading |
上面这些 + 页内各级标题 | 标题写得足够具体时 |
summary |
上面这些 + 描述与摘要 | 千页级站点;本站使用这一档 |
content |
上面这些 + 全文纯文本 | 默认值,几百页以内适用 |
其它取值会报 invalid params.offline_search_index 告警并使用 content。
offline_search_summary_length 是结果行里摘要的截断长度(默认 70),offline_search_max_results 是结果条数上限(默认 10)。这几个键的完整定义在配置总览。
读者搜第一个词之前要先下载整份索引。超过这个量级就把 offline_search_index 从 content 降到 summary。
调整排序
页面在 front matter 里影响自己的排名:
search_keywords 是额外的匹配词,可以写一个字符串,也可以写数组。它是这两个键里更有用的一个:读者搜 pg 或 GUC 即可命中标题只写着「PostgreSQL 参数」的页面。检索时关键词的权重仅次于标题,高于正文。
search_boost 是最终得分的正数乘子,默认 1.0,作用在文本匹配得分之上。1.5 不会把页面固定在第一位,在 OINK 1.4.0 中,只让它在相同关键词覆盖率与短语层级内前移。零、负数与非数字会告警并按 1.0 处理。
整节的默认值用 cascade 一次设定:
页面自己写的值覆盖继承来的值。本站 docs/ 下的页面按这种方式使用 search_keywords:每页列出中文说法、英文原词与配置键名。
把页面挡在索引外
search_exclude 是唯一写法。已移除的 exclude_search 与 excludeSearch 不再被
读取,因此不能保护页面;迁移检查器会报告它们。正文为空的页面不进索引。
不该公开的内容不要放进站点,也不要用 search_exclude 保护它。
中文、混合查询与标识符
以下行为已随 v1.4.0 发布。
搜索按空白和拉丁文字与 CJK 的边界拆词:PostgreSQL 备份 与 PostgreSQL备份
都会查询 postgresql 和 备份。连续的 CJK 字串仍按字面子串匹配,不使用词典;
主从复制 不等于 复制主从。请用空格分隔概念,例如 连接池 超时。
search_keywords 仍适合补充同义说法与缩写。
搜索保留下划线、连字符、点号、路径与命令选项。可以查询 shared_buffers、
pg_basebackup、--baseURL 或 /pg/data。这些内容按字面标识符处理,不作为
查询运算符或拼写纠错对象。英文词保留 Lunr 词干匹配;某个词没有精确或词干命中时,
5–7 个字符的词最多允许一次编辑,更长的词最多允许两次。短词和标识符使用字面子串匹配。
查询会统一大小写与 Unicode 全半角,最多使用 24 个不同的词。
关键词可以分布在不同字段中:标题含 PostgreSQL、描述含 备份,即可覆盖两个词。
排序规则如下:
- 有页面覆盖全部关键词时,只显示这些页面。否则显示标注命中词数与总词数的部分匹配,优先展示覆盖更多词的页面。
- 覆盖率相同时,连续完整短语优先。
- 在上述层级内部,把字段得分乘以
search_boost。每个词取最强字段,依次为页面标题、关键词、标签与分类、页内标题、描述、正文。同一字段中多次出现该词的页面,排在只出现一次的页面之前,但不会超过命中更强字段的页面。仍然同分时按标题和 URL 稳定排序。
输入过程中的字面子串也能命中。加权不能让部分匹配超过完整匹配。 结果仍按顶栏的栏目顺序分组;先应用全局结果数量上限,再在组内保留排序。 仅命中关键词时显示页面描述或摘要,不显示同义词列表。
同页多个小节命中时只占一行,显示最相关的小节标题与附近文字,并打开真实渲染的标题 ID。
显式 ID、自动生成的重复标题 ID、中文标题和部署子路径都保留。只有元数据命中、没有小节
命中时打开页面。heading 和 summary 范围可以定位标题命中;只出现在正文里的词需要
content。索引不会隐式扩大为全文。命中摘要展示附近最多 160 个字符;配置的摘要长度仍
控制无上下文命中时的后备摘录。
面板中的 搜索范围 并排显示全部栏目与当前顶层栏目(如文档、博客、书籍),点击即可切换。 每次加载页面默认全部栏目,在同页关闭再打开面板时保留选择。首页没有当前栏目。 命令和页面操作继续可用,命令模式隐藏范围控件。用 Tab 到达选中的范围,方向键切换, 再按 Tab 回到查询框;在查询框中按 Shift+Tab 则回到选中的范围。
输入法组字期间暂停结果更新与 Enter 激活,文字上屏后再检索。 空结果、加载中、索引不可用、结果数量与部分匹配状态都有可读文字,并向屏幕阅读器播报。
可选:在线搜索
本地搜索之外,主题保留了两个在线搜索集成,默认关闭。同一时间只启用一种:配置了多个入口时构建告警 You have more than one site-search option configured。
启用在线搜索意味着接受对应服务的抓取方式、可用性与隐私边界,这些应写进站点的隐私说明。
Algolia DocSearch
三个值必须都显式写出。缺任意一项都会告警并停用 Algolia。OINK 不会回退到其它项目的公共索引。DocSearch 的 JS 与 CSS 随主题内置,不从 CDN 加载,但每次检索请求都发到 Algolia。需要真实的密钥与索引才能工作,此处不渲染。
Google 可编程搜索
还需要给结果准备一个落地页:
搜索框把查询提交到 <baseURL>/search/?q=…,结果由 Google 的脚本在那个页面上渲染,需要访问 cse.google.com。同样需要外部服务,此处不渲染。
验证
-
构建,确认每种语言各生成了一份索引:
开发构建下文件名是
offline-search-index.zh.json,生产构建加指纹,形如offline-search-index.zh.7ab….json。一种语言一个文件,缺少某个文件说明那种语言的页面没进索引。 -
查看索引内容,这是排查「中文搜不到」的第一步:
条目数应接近中文页面数,
keywords与boost字段能看到写进 front matter 的值。 -
打开站点,按 /,分别用一个英文词与一个中文词各搜一次。结果按内容根分组,每组的名字是面包屑的第一段。
-
子路径部署(站点挂在
https://example.com/docs/这类路径下)时,打开浏览器开发者工具的网络面板,确认索引请求带上了子路径。索引请求打到域名根目录并返回 404、页面其余部分正常,是「搜索没结果」最常见的原因。
相关
- 命令面板 — 搜索的入口,以及面板里的命令与页面动作
- 键盘导航 — 打开搜索与打开命令的四个单键
- 多语言 — 分语言索引与缺译回退
- 配置总览 —
offline_search*各键的完整定义 - 页面参数 —
search_keywords/search_boost/search_exclude