github.com/jbramsden/hugo@v0.47.1/docs/content/en/content-management/related.md (about)

     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  {{% note %}}
    18  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).
    19  {{% /note %}}
    20  
    21  ## List Related Content
    22  
    23  To list up to 5 related pages 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  
    38  {{% note %}}
    39  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.
    40  {{% /note %}}
    41  
    42  The full set of methods available on the page lists can be seen in this Go interface:
    43  
    44  ```go
    45  // A PageGenealogist finds related pages in a page collection. This interface is implemented
    46  // by Pages and PageGroup, which makes it available as `{{ .RegularPages.Related . }}` etc.
    47  type PageGenealogist interface {
    48  
    49  	// Template example:
    50  	// {{ $related := .RegularPages.Related . }}
    51  	Related(doc related.Document) (Pages, error)
    52  
    53  	// Template example:
    54  	// {{ $related := .RegularPages.RelatedIndices . "tags" "date" }}
    55  	RelatedIndices(doc related.Document, indices ...interface{}) (Pages, error)
    56  
    57  	// Template example:
    58  	// {{ $related := .RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks")  ( keyVals "date" .Date ) }}
    59  	RelatedTo(args ...types.KeyValues) (Pages, error)
    60  }
    61  ```
    62  ## Configure Related Content
    63  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.
    64  
    65  {{% note %}}
    66  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.
    67  {{% /note %}}
    68  
    69  Below is a sample `config.toml` section:
    70  
    71  ```
    72  [related]
    73  
    74  # Only include matches with rank >= threshold. This is a normalized rank between 0 and 100.
    75  threshold = 80
    76  
    77  # To get stable "See also" sections we, by default, exclude newer related pages.
    78  includeNewer = false
    79  
    80  # Will lower case keywords in both queries and in the indexes.
    81  toLower = false
    82  
    83  [[related.indices]]
    84  name = "keywords"
    85  weight = 150
    86  [[related.indices]]
    87  name  = "author"
    88  toLower = true
    89  weight = 30
    90  [[related.indices]]
    91  name  = "tags"
    92  weight = 100
    93  [[related.indices]]
    94  name  = "date"
    95  weight = 10
    96  pattern = "2006"
    97  ```
    98  ### Top Level Config Options
    99  
   100  threshold
   101  :  A value between 0-100. Lower value will give more, but maybe not so relevant, matches.
   102  
   103  includeNewer
   104  :  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.
   105  
   106  toLower
   107  : 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.
   108  
   109  ### Config Options per Index
   110  
   111  name
   112  :  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. 
   113  
   114  weight
   115  : 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.
   116  
   117  pattern
   118  : 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.
   119  
   120  toLower
   121  : See above.
   122  
   123  ## Performance Considerations
   124  
   125  **Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast. 
   126  
   127  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:
   128  
   129  {{< tweet 898398437527363585 >}}
   130  
   131  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. 
   132  
   133  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:
   134  
   135  * 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.
   136  * 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.
   137  
   138  
   139  
   140  
   141  
   142  
   143