mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-30 22:39:58 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '13e64d72763bf8d6d92d4cdfc15ed45ee9debfab'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2018-09-14 08:35:23 +02:00
parent 9b26b5487b 13e64d7276
commit b7ca3e1b3a
48 changed files with 566 additions and 350 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
docs/content/en/content-management/related.md
View File

@@ -14,13 +14,13 @@ aliases: [/content/related/,/related/]
toc: true
---
{{% 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](https://github.com/joearms/sherlock).
{{% /note %}}
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).
## List Related Content
To list up to 5 related pages is as simple as including something similar to this partial in your single page template:
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 }}
@@ -34,67 +34,62 @@ To list up to 5 related pages is as simple as including something similar to thi
{{ end }}
{{< /code >}}
### Methods
Here is the list of "Related" methods available on a page collection such `.RegularPages`.
#### .Related PAGE
Returns a collection of pages related the given one.
```
{{ $related := .RegularPages.Related . }}
```
#### .RelatedIndices PAGE INDICE1 [INDICE2 ...]
Returns a collection of pages related to a given one restricted to a list of indices.
```
{{ $related := .RegularPages.RelatedIndices . "tags" "date" }}
```
#### .RelatedTo KEYVALS [KEYVALS2 ...]
Returns a collection of pages related together by a set of indices and their match.
In order to build those set and pass them as argument, one must use the `keyVals` function where the first agrument would be the `indice` and the consective ones its potential `matches`.
```
{{ $related := .RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }}
```
{{% note %}}
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.
{{% /note %}}
The full set of methods available on the page lists can be seen in this Go interface:
```go
// A PageGenealogist finds related pages in a page collection. This interface is implemented
// by Pages and PageGroup, which makes it available as `{{ .RegularPages.Related . }}` etc.
type PageGenealogist interface {
// Template example:
// {{ $related := .RegularPages.Related . }}
Related(doc related.Document) (Pages, error)
// Template example:
// {{ $related := .RegularPages.RelatedIndices . "tags" "date" }}
RelatedIndices(doc related.Document, indices ...interface{}) (Pages, error)
// Template example:
// {{ $related := .RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }}
RelatedTo(args ...types.KeyValues) (Pages, error)
}
```
## 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.
```yaml
related:
threshold: 80
includeNewer: false
toLower: false
indices:
- name: keywords
weight: 100
- name: date
weight: 10
```
Custom configuration should be set using the same syntax.
{{% note %}}
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.
{{% /note %}}
Below is a sample `config.toml` section:
```
[related]
# Only include matches with rank >= threshold. This is a normalized rank between 0 and 100.
threshold = 80
# To get stable "See also" sections we, by default, exclude newer related pages.
includeNewer = false
# Will lower case keywords in both queries and in the indexes.
toLower = false
[[related.indices]]
name = "keywords"
weight = 150
[[related.indices]]
name = "author"
toLower = true
weight = 30
[[related.indices]]
name = "tags"
weight = 100
[[related.indices]]
name = "date"
weight = 10
pattern = "2006"
```
### Top Level Config Options
threshold
@@ -135,9 +130,6 @@ He should now be able to add an improved version of that "Related Content" secti
* 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](https://github.com/joearms/sherlock).
{{% /note %}}