hugo/content/en/content-management/related.md
Bjørn Erik Pedersen 35dec7c96f Squashed 'docs/' changes from 4d936aee6..4dd2d6415
4dd2d6415 Fix erroridf example
9ae8e9199 Clarify highlight options
f3943f9c8 Fix typo
b57ea5ac8 Add field to glossary of terms
3191e35b4 Clarify comment in the new-in shortcode
870c8d35c Correct description of Ref and RelRef page methods
c9df50e6e Specify encoding in description of crypto functions
749bb37e2 Add Ref, RelRef, and Site shortcode methods
994d4374b Update fmt functions
740f5ef96 Misc additions
77acdcdb6 Remove rssLimit from root config documentation
df84a1795 Document the openapi3.Unmarshal function
24236f57d Miscellaneous edits and corrections
41b54d421 Hide the "new in" button after some period of time
3c1ebac31 Update Ancestors.md
e699eb313 Add new-in tags to select functions and methods
5c41f0bf8 Clarify time.Format method
f7bd43ae1 Add link to built-in render hook for GoAT diagrams
06f9cd4c9 Document the diagrams.Goat function
5e432e12d Adjust quick reference weights
fc915efd6 Update FAQ
5bccf8b19 Use LinkTitle consistently in examples
36f207f3a Add page collection quick reference
699de883d Inlcude example of newScratch.Values
9bb7f8c78 Include RenderString example for emoji shortcodes
783fdd3ac Fix typo
26d5a4399 Fix typo
c7e86f0cf Fix typo
ad2a82fbd Clarify data type returned by partial and partialCached
1de5a52dd Miscellaneous corrections
3509e1b4d Update configuration-markup.md
8c6a9bf02 Clairfy figure shortcode output
c9d0dc8fb Update Markdownify.md
0c4bc1447 Update theme
0f0ab2ade Add methods deprecated in v0.120.0
e1c6ecd0f Miscellaneous edits
ec53b55b9 netlify: Hugo 0.120.4
23a1f3fd5 templates/internal.md: Correct GoogleAnalytics key name
6dcfa9a82 Update troubleshooting section
0c8857e8f Adjust code and code-toggle shortcodes
8820264d3 Reduce number of site audit warnings
526d06b90 Clarify hint option in image processing spec
310849daa Image Processing: Improve sentence and fix code sample
5bb67bfd4 Revert "Image Processing: Improve sentence and fix code sample" (#2318)
77c926fde Image Processing: Improve sentence and fix code sample
52179fb18 Miscellaneous edits
f4e886715 Revert change to hugo.work
c410fefa8 Update theme
8b72dfedd Rework where function documentation
f35a7126f Minor edits to global page function
903b42ebc Cleanup shortcode calls
c9247e98d Update documentation.md
dff3c4abb Clean up build option descriptions and examples
f46d31308 Use consistent signatures
2af2470b5 Minor correction to resources.GetRemote
45ec53fe0 Remove superfluous shortcode param
2a0544757 Improve deployment documentation
3cf36a7fc Clarify lang keyword
f10d6495d Update front-matter.md
dc94e20be Add Sveltia to CMS list
b15d6d670 Update front-ends.md
bb41588b2 Update FormatCurrency.md
b40fff396 Add showcase for hidden sections without index.html
71316e181 Improve image filter examples
d46f0b1d8 Miscellaneous edits
ad3f9cdb6 Adjust quick reference guides
8657804ba Update theme
d9e981147 Miscellaneous corrections
508666575 Miscellaneous updates
80b2241f9 Miscellaneous updates
723a827fd Namespace functions and methods
40212779a netlify: Hugo 0.120.3
66017c704 Bump GitHub workflows to latest versions
db0f1e682 Update related.md
7e758c23b netlify: Hugo 0.120.2
641ba3976 Update configuration.md
d2a9909d9 Update rss.md
7eb59d7a2 netlify: Hugo 0.120.1
708c351c4 Document debug.Timer
28e2388c2 Add new-in tag to images.Padding
ee24cffb5 Add new-in tags to hugo.IsDevelopment and hugo.IsServer
aa47ca023 netlify: Hugo 0.120.0
9c3e606fc docs: Regen docshelper
159fd971e commands/new: Remove format flag from new content cmd
9f7878092 Merge commit 'aaaf1c8df5d6aa061609d20510f7fa6c42e5cc1a'
65b2dd324 docs: Regenerate docshelper
2be620663 resources/images: Create padding image filter
c777d6c5e Merge commit '3710a5ec7efe6baca6e452f43632c05d22bab3c4'
24f2afeb2 Merge commit 'e509cac533600cf4fa8382c9cdab78ddd82db688'
3f947c19a hugolib: Deprecate .Site.DisqusShortname
6bd1af892 hugolib: Deprecate .Site.GoogleAnalytics
78becc6ee tpl/tplimpl: Deprecate .Site.Social usage with internal templates
e3ec2a4f2 common/hugo: Add hugo.IsServer and hugo.IsDevelopment

git-subtree-dir: docs
git-subtree-split: 4dd2d641531f74025ed9f51ea5a961e936988cfb
2023-12-04 15:14:18 +01:00

7.6 KiB

title description categories keywords menu weight toc aliases
Related content List related content in "See Also" sections.
content management
content
docs
parent weight
content-management 110
110 true
/content/related/
/related/

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.

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:

{{< code file=layouts/partials/related.html >}} {{ $related := .Site.RegularPages.Related . | first 5 }} {{ with $related }}

See Also

    {{ range . }}
  • {{ .LinkTitle }}
  • {{ end }}
{{ end }} {{< /code >}}

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")
}}

{{% note %}} We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: Related, RelatedTo and RelatedIndices. Now we have only one method: Related. The old methods are still available but deprecated. Also see this blog article for a great explanation of more advanced usage of this feature. {{% /note %}}

{{< new-in 0.111.0 >}}

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:

{{< code-toggle file=hugo >}} [related] threshold = 20 includeNewer = true toLower = false related.indices name = "fragmentrefs" type = "fragments" applyFilter = true weight = 80 {{< /code-toggle >}}

  • 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 applyFilteris 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 }}

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.

{{< code-toggle config=related />}}

Custom configuration should be set using the same syntax.

{{% note %}} If you add a related configuration 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. {{% /note %}}

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 {{< new-in 0.111.0 >}}
(string) One of basic(default) or fragments.
applyFilter {{< new-in 0.111.0 >}}
(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 {{< new-in 0.111.0 >}}
(int) A percentage (0-100) used to remove common keywords from the index. As an example, setting this to 50 will remove all keywords that are used in more than 50% of the documents in 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.

Performance considerations

Fast is Hugo's middle name and we would not have released this feature had it not been blistering fast.

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:

{{< tweet user="scott_lowe" id="898398437527363585" >}}

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.

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:

  • 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.
  • 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.

{{% note %}} 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. {{% /note %}}