hugo/docs/content/en/content-management/related.md at 7732da9f93503c1a723d6ac5bb77da206cb0fa0e

mirror of https://github.com/gohugoio/hugo.git synced 2024-11-07 20:30:36 -05:00

Joe Mooring 0cc39af682 Update Twitter shortcode oEmbed endpoint

The existing endpoint will be retired and removed on November 23, 2021.
References:

- https://twittercommunity.com/t/consolidating-the-oembed-functionality/154690
- https://developer.twitter.com/en/docs/twitter-for-websites/oembed-api#Embedded

This is a backward compatible change.

The existing endpoint requires a single parameter: the id of the tweet.

The new endpoint requires two parameters: the id of the tweet, and the
user with whom it is associated. For the moment, if you supply the wrong
user, the request will be redirected (with a small delay) to the correct
user/id pair. This behavior is undocumented, but we will take advantage
of it as Hugo site authors transition to the new syntax.

{{< tweet 1453110110599868418 >}} --> works, throws warning, deprecate at some point

{{< tweet user="SanDiegoZoo" id="1453110110599868418" >}} --> new syntax

Fixes #8130

2021-11-01 15:51:00 +01:00

5.7 KiB

Raw Blame History

title

description

date

Methods

Here is the list of "Related" methods available on a page collection such .RegularPages.

Returns a collection of pages related the given one.

{{ $related := .Site.RegularPages.Related . }}

.RelatedIndices PAGE INDICE1 [INDICE2 ...]

Returns a collection of pages related to a given one restricted to a list of indices.

{{ $related := .Site.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 argument would be the indice and the consecutive ones its potential matches.

{{ $related := .Site.RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks")  ( keyVals "date" .Date ) }}

{{% note %}} Read this blog article for a great explanation of more advanced usage of this feature. {{% /note %}}

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 file="config" >}} related: threshold: 80 includeNewer: false toLower: false indices:

name: keywords weight: 100
name: date weight: 10 {{< /code-toggle >}}

Note that if you have configured tags as a taxonomy, tags will also be added to the default configuration above with the weight of 80.

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 %}}

Top Level Config Options

threshold: A value between 0-100. Lower value will give more, but maybe not so relevant, matches.
includeNewer: 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: 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.

Config Options per Index

name: 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.
weight: 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.
pattern: 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: 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:

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 %}}

5.7 KiB Raw Blame History

List Related Content

See Also