相关内容配置
通过索引与阈值控制相关内容的匹配方式。
这一页解决什么问题
[related] 决定 Pages.Related 方法如何判断「哪些页面相关」:拿哪些页面参数当索引、各占多少权重、相似度阈值多高。有了它,文章底部的「相关阅读」就不必自己写筛选逻辑。
最容易踩的坑(上游加粗提醒):一旦在项目配置里写下 related 区段,就必须给出完整配置——不能只指定要覆盖的几个键,而把其余留空。
什么时候需要这些设置
| 设置 | 什么时候需要 | 改错了会看到什么现象 |
|---|---|---|
related 区段整体 |
想在文章页展示「相关阅读」 | 只写部分键、其余留空 → 索引与阈值被清空,Related 返回空列表或结果毫不相关 |
threshold |
相关条目太多或太少(范围 [0, 100]) |
调低 → 匹配变多但相关性变弱;调高 → 相关列表可能为空 |
indices[].name / weight |
决定以什么为相关依据(tags、keywords、author、title 等) |
name 与页面参数名不一致 → 该索引取不到值,等于没配;weight 为 0 相当于关闭该索引 |
includeNewer |
希望旧文章也能关联到新内容 | 保持 false 时,新内容不会出现在旧文章的相关列表里,容易被误当成 bug |
tokenize + minTokenLength |
想按标题或正文里的词关联,而不是整串文本 | 不设 minTokenLength → the、and 之类短词也参与匹配,噪声很大;不以空白分词的语言不受支持(上游明确) |
默认配置
Hugo 自带一套合理的相关内容识别配置,你可以在项目配置中全局或按语言自定义它。默认配置如下:
[related]
includeNewer = false
threshold = 80
toLower = false
[[related.indices]]
applyFilter = false
cardinalityThreshold = 0
minTokenLength = 0
name = 'keywords'
pattern = ''
toLower = false
tokenize = false
type = 'basic'
weight = 100
[[related.indices]]
applyFilter = false
cardinalityThreshold = 0
minTokenLength = 0
name = 'date'
pattern = ''
toLower = false
tokenize = false
type = 'basic'
weight = 10
[[related.indices]]
applyFilter = false
cardinalityThreshold = 0
minTokenLength = 0
name = 'tags'
pattern = ''
toLower = false
tokenize = false
type = 'basic'
weight = 80一旦在项目配置里加上
related区段,就必须给出完整配置:不能只指定要覆盖的那几个设置,而把其余设置留空。渲染相关内容请使用模板中的Pages.Related方法。
顶层设置
| 键名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
threshold |
int |
80 |
取值范围 [0, 100]。值越低匹配到的内容越多,但相关性可能越弱。 |
includeNewer |
bool |
false |
是否把发布日期晚于当前页面的内容纳入相关列表。开启后,旧文章的相关列表会随着新增内容而变化。 |
toLower |
bool |
false |
是否把索引与查询中的关键词统一转为小写。结果可能更准确,但有轻微的性能开销。 |
索引设置
| 键名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
indices[].name |
string |
— | 索引名。该值直接对应一个页面参数,Hugo 支持 author 这类字符串值、tags 与 keywords 这类列表,以及时间和日期对象。 |
indices[].weight |
int |
0 |
该索引相对其他索引的重要性。可以为 0(相当于关闭该索引),甚至可以为负。内置默认配置中,keywords 为 100、tags 为 80、date 为 10。 |
indices[].type |
string |
basic |
取 basic 或 fragments 之一。 |
indices[].pattern |
string |
'' |
仅对日期有意义。默认配置中该值为空;原文指出日期索引的默认模式是 2006,把它显式写进 pattern 会让同年发布的页面获得额外权重;更新频繁的站点可改用 200601,即按年月加权。 |
indices[].applyFilter |
bool |
false |
是否对搜索结果应用某个 type 专属的过滤。仅用于 fragments 类型。 |
indices[].cardinalityThreshold |
int |
0 |
取值范围 [1, 100] 的百分比阈值,出现频率高于该阈值的索引值会被移出索引。例如 60 会移除出现在超过 60% 文档中的索引值;0 表示禁用过滤。 |
indices[].minTokenLength |
int |
0 |
(自 v0.166.0 起)当 tokenize 为 true 时,以 Unicode 码点计算的最短词长。可用它排除 a、in、the 这类短词,而不必考虑其出现频率。该设置先于 cardinalityThreshold 生效,被排除的词不会进入索引。默认 0 表示不设下限。 |
indices[].tokenize |
bool |
false |
(自 v0.166.0 起)是否在建立索引前按空白切分字符串值。 |
indices[].toLower |
bool |
false |
是否把索引与查询中的关键词统一转为小写,含义与顶层同名设置一致。 |
tokenize 有一些需要留意的行为:对 fragments 类型的索引,非标题片段(例如描述列表的术语)始终按其精确标识符建立索引;分词会让索引体积随每个值的词数增长,可配合 minTokenLength 排除短词、cardinalityThreshold 移除高频词;apple 与 apples 这类单复数形式会被视为不同的词,不以空白分词的中日韩语言及其他文字系统不受支持。
示例:按分类法术语关联
设想一个书评站点,正文是书评,用类型与作者作为分类法(taxonomy)。我们希望访客查看某篇书评时,看到一份基于共享作者和类型的相关书评列表。
先声明分类法:
[taxonomies]
author = 'authors'
genre = 'genres'再配置相关内容的识别方式:
[related]
includeNewer = true
threshold = 80
toLower = true
[[related.indices]]
name = 'authors'
weight = 2
[[related.indices]]
name = 'genres'
weight = 1authors 索引的权重是 2,genres 是 1,也就是说共享作者的份量是共享类型的两倍。渲染时用模板取回 5 条相关书评即可,例如 site.RegularPages.Related . | first 5。
示例:按标题词关联
再设想一个博客,希望标题中含有相同词语的文章互相关联:标题为 “Hugo image processing” 的文章,应当匹配标题中含有 Hugo、image 或 processing 的文章。
[related]
threshold = 50
toLower = true
[[related.indices]]
name = 'title'
weight = 1
tokenize = true
minTokenLength = 4tokenize 为 true 时,Hugo 按空白切分每个页面标题,并为切分出的单词分别建立索引;minTokenLength = 4 会排除 and、the、for 这类短词。渲染方式与上一个示例相同。
延伸阅读
常见坑
| 症状 | 真因 | 怎么修 |
|---|---|---|
Related 返回空列表 |
related 区段只写了部分设置,索引被清空;或 threshold 过高 |
按本页默认配置补齐完整区段,再逐步调参 |
| 相关结果看起来毫不相关 | 索引选得不合适(例如把 date 当主要依据),或权重分配不合理 |
给语义相近的索引更高权重(默认 keywords 100、tags 80、date 10) |
| 配置改了页面没变化 | 模板没有调用 Pages.Related(上游明确需要模板侧配合) |
见相关内容 |
| 中文内容按标题词关联不生效 | tokenize 依赖空白分词,不以空白分词的语言不受支持 |
改用分类法或页面参数(如 keywords)做关联 |
| 报错看不懂 | 该区段一般不报错,表现为「结果为空或不准」 | 见故障排查 |
更多排查入口见故障排查。