Related content

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.

List related content

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 template:

{{ $related := .Site.RegularPages.Related . | first 5 }}
{{ with $related }}
  <h3>See Also</h3>
  <ul>
   {{ range . }}
     <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
   {{ end }}
  </ul>
{{ end }}

The Related method takes one argument which may be a Page or a options map. The options map have these options:

indices

(slice) The indices to search within.

document

(page) The page for which to find related content. Required when specifying an options map.

namedSlices

(slice) The keywords to search for, expressed as a slice of KeyValues using the keyVals function.

fragments

(slice) A list of special keywords that is used for indices configured as type “fragments”. This will match the fragment identifiers of the documents.

A fictional example using all of the above options:

{{ $page := . }}
{{ $opts := dict
  "indices" (slice "tags" "keywords")
  "document" $page
  "namedSlices" (slice (keyVals "tags" "hugo" "rocks") (keyVals "date" $page.Date))
  "fragments" (slice "heading-1" "heading-2")
}}

Index content headings in related content

Hugo can index the headings in your content and use this to find related content. You can enable this by adding a index of type fragments to your related configuration:

related:
  includeNewer: true
  indices:
  - applyFilter: true
    name: fragmentrefs
    type: fragments
    weight: 80
  threshold: 20
  toLower: false

[related]
  includeNewer = true
  threshold = 20
  toLower = false
  [[related.indices]]
    applyFilter = true
    name = 'fragmentrefs'
    type = 'fragments'
    weight = 80

{
   "related": {
      "includeNewer": true,
      "indices": [
         {
            "applyFilter": true,
            "name": "fragmentrefs",
            "type": "fragments",
            "weight": 80
         }
      ],
      "threshold": 20,
      "toLower": false
   }
}

• The name maps to a optional front matter slice attribute that can be used to link from the page level down to the fragment/heading level.
• If applyFilter is enabled, the .HeadingsFiltered on each page in the result will reflect the filtered headings. This is useful if you want to show the headings in the related content listing:

{{ $related := .Site.RegularPages.Related . | first 5 }}
{{ with $related }}
  <h2>See Also</h2>
  <ul>
    {{ range $i, $p := . }}
      <li>
        <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
        {{ with .HeadingsFiltered }}
          <ul>
            {{ range . }}
              {{ $link := printf "%s#%s" $p.RelPermalink .ID | safeURL }}
              <li>
                <a href="{{ $link }}">{{ .Title }}</a>
              </li>
            {{ end }}
          </ul>
        {{ end }}
      </li>
    {{ end }}
  </ul>
{{ end }}

Configure related content

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.

Default configuration

Without any related configuration set on the project, Hugo’s Related Content methods will use the following.

related:
  includeNewer: false
  indices:
  - applyFilter: false
    cardinalityThreshold: 0
    name: keywords
    pattern: ""
    toLower: false
    type: basic
    weight: 100
  - applyFilter: false
    cardinalityThreshold: 0
    name: date
    pattern: ""
    toLower: false
    type: basic
    weight: 10
  - applyFilter: false
    cardinalityThreshold: 0
    name: tags
    pattern: ""
    toLower: false
    type: basic
    weight: 80
  threshold: 80
  toLower: false

[related]
  includeNewer = false
  threshold = 80
  toLower = false
  [[related.indices]]
    applyFilter = false
    cardinalityThreshold = 0
    name = 'keywords'
    pattern = ''
    toLower = false
    type = 'basic'
    weight = 100
  [[related.indices]]
    applyFilter = false
    cardinalityThreshold = 0
    name = 'date'
    pattern = ''
    toLower = false
    type = 'basic'
    weight = 10
  [[related.indices]]
    applyFilter = false
    cardinalityThreshold = 0
    name = 'tags'
    pattern = ''
    toLower = false
    type = 'basic'
    weight = 80

{
   "related": {
      "includeNewer": false,
      "indices": [
         {
            "applyFilter": false,
            "cardinalityThreshold": 0,
            "name": "keywords",
            "pattern": "",
            "toLower": false,
            "type": "basic",
            "weight": 100
         },
         {
            "applyFilter": false,
            "cardinalityThreshold": 0,
            "name": "date",
            "pattern": "",
            "toLower": false,
            "type": "basic",
            "weight": 10
         },
         {
            "applyFilter": false,
            "cardinalityThreshold": 0,
            "name": "tags",
            "pattern": "",
            "toLower": false,
            "type": "basic",
            "weight": 80
         }
      ],
      "threshold": 80,
      "toLower": false
   }
}

Custom configuration should be set using the same syntax.

Top level configuration options

threshold

(int) A value between 0-100. Lower value will give more, but maybe not so relevant, matches.

includeNewer

(bool) 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.

toLower

(bool) 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.

Configuration options per index

name

(string) The index name. This value maps directly to a page parameter. Hugo supports string values (author in the example) and lists (tags, keywords etc.) and time and date objects.

type

(string) One of basic(default) or fragments.

applyFilter

(string) Apply a type specific filter to the result of a search. This is currently only used for the fragments type.

weight

(int) 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.

cardinalityThreshold

(int) If between 1 and 100, this is a percentage. All keywords that are used in more than this percentage of documents are removed. For example, setting this to 60 will remove all keywords that are used in more than 60% of the documents in the index. If 0, no keyword is removed from the index. Default is 0.

pattern

(string) 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.

toLower

(bool) See above.