diff --git a/content/en/content-management/related.md b/content/en/content-management/related.md index 2d2077c81c..bd3a5d4666 100644 --- a/content/en/content-management/related.md +++ b/content/en/content-management/related.md @@ -31,40 +31,82 @@ To list up to 5 related pages (which share the same _date_ or _keyword_ paramete {{ end }} {{< /code >}} -### Methods +The `Related` method takes one argument which may be a `Page` or a options map. The options map have these options: -Here is the list of "Related" methods available on a page collection such `.RegularPages`. +indices +: The indices to search in. -#### .Related PAGE +document +: The document to search for related content for. -Returns a collection of pages related the given one. +namedSlices +: The keywords to search for. + +fragments +: Fragments holds a 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: ```go-html-template -{{ $related := site.RegularPages.Related . }} +{{ $page := . }} +{{ $opts := + "indices" (slice "tags" "keywords") + "document" $page + "namedSlices" (slice (keyVals "tags" "hugo" "rocks") (keyVals "date" $page.Date)) + "fragments" (slice "heading-1" "heading-2") +}} ``` -#### .RelatedIndices PAGE INDICE1 [INDICE2 ...] +{{% note %}} +We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndicies`. Now we have only one method: `Related`. The old methods are still available but deprecated. Also see [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. +{{% /note %}} + +## Index Content Headings in Related Content -Returns a collection of pages related to a given one restricted to a list of indices. +{{< new-in "0.111.0" >}} -```go-html-template -{{ $related := site.RegularPages.RelatedIndices . "tags" "date" }} -``` +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: -#### .RelatedTo KEYVALS [KEYVALS2 ...] -Returns a collection of pages related together by a set of indices and their match. +```toml +[related] +threshold = 20 +includeNewer = true +toLower = false +[[related.indices]] +name = "fragmentrefs" +type = "fragments" +applyFilter = false +weight = 80 +``` -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`. +* 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: ```go-html-template -{{ $related := site.RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }} +{{ $related := .Site.RegularPages.Related . | first 5 }} +{{ with $related }} +