related.md (5849B)
1 ---
2 title: Related Content
3 description: List related content in "See Also" sections.
4 date: 2017-09-05
5 categories: [content management]
6 keywords: [content]
7 menu:
8 docs:
9 parent: "content-management"
10 weight: 40
11 weight: 30
12 draft: false
13 aliases: [/content/related/,/related/]
14 toc: true
15 ---
16
17
18 Hugo uses a set of factors to identify a page's related content based on Front Matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content).
19
20 ## List Related Content
21
22
23 To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your single page template:
24
25 {{< code file="layouts/partials/related.html" >}}
26 {{ $related := .Site.RegularPages.Related . | first 5 }}
27 {{ with $related }}
28 <h3>See Also</h3>
29 <ul>
30 {{ range . }}
31 <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
32 {{ end }}
33 </ul>
34 {{ end }}
35 {{< /code >}}
36
37 ### Methods
38
39 Here is the list of "Related" methods available on a page collection such `.RegularPages`.
40
41 #### .Related PAGE
42 Returns a collection of pages related the given one.
43
44 ```
45 {{ $related := site.RegularPages.Related . }}
46 ```
47
48 #### .RelatedIndices PAGE INDICE1 [INDICE2 ...]
49 Returns a collection of pages related to a given one restricted to a list of indices.
50
51 ```
52 {{ $related := site.RegularPages.RelatedIndices . "tags" "date" }}
53 ```
54
55 #### .RelatedTo KEYVALS [KEYVALS2 ...]
56 Returns a collection of pages related together by a set of indices and their match.
57
58 In order to build those set and pass them as argument, one must use the `keyVals` function where the first argument would be the `indice` and the consecutive ones its potential `matches`.
59
60 ```
61 {{ $related := site.RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }}
62 ```
63
64 {{% note %}}
65 Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature.
66 {{% /note %}}
67
68 ## Configure Related Content
69 Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed.
70
71 ### Default configuration
72
73 Without any `related` configuration set on the project, Hugo's Related Content methods will use the following.
74
75 {{< code-toggle file="config" >}}
76 related:
77 threshold: 80
78 includeNewer: false
79 toLower: false
80 indices:
81 - name: keywords
82 weight: 100
83 - name: date
84 weight: 10
85 {{< /code-toggle >}}
86
87 Note that if you have configured `tags` as a taxonomy, `tags` will also be added to the default configuration above with the weight of `80`.
88
89 Custom configuration should be set using the same syntax.
90
91 {{% note %}}
92 If you add a `related` config section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults.
93 {{% /note %}}
94
95 ### Top Level Config Options
96
97 threshold
98 : A value between 0-100. Lower value will give more, but maybe not so relevant, matches.
99
100 includeNewer
101 : Set to true to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added.
102
103 toLower
104 : Set to true to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index.
105
106 ### Config Options per Index
107
108 name
109 : The index name. This value maps directly to a page param. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects.
110
111 weight
112 : An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be 0, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best.
113
114 pattern
115 : This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default.
116
117 toLower
118 : See above.
119
120 ## Performance Considerations
121
122 **Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast.
123
124 This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread:
125
126 {{< tweet user="scott_lowe" id="898398437527363585" >}}
127
128 Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog.
129
130 He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that:
131
132 * If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before.
133 * Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites.
134
135 {{% note %}}
136 We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock).
137 {{% /note %}}