Getting started with Related Content

support
1

Hello! I’m trying to use the related content feature but I don’t think I fully understand it. I’m happy to update the documentation once I do, but would like to confirm with all you lovely people, first…

Per the docs, I was hoping I could just use .Site.RegularPages.Related and see other posts in the same section without changing anything else.

After a bit of digging, it appears you MUST configure at least one index (e.g. ‘keywords’ or ‘tags’) and include this data in the front matter.

e.g. my config.yaml looks like this:

title: My New Hugo Site
related:
  includeNewer: true
  indices:
    - name: keywords # The name of the indice, same as Front Matter's .Param key.
      weight: 1 # We don't really need this, but omitting it would disable the index.

And each post includes keywords: blog in the front matter.

See the full repo for details.

Am I correct in thinking that there’s no way to use .Site.RegularPages.Related without configuring at least one index and adding the relevant front matter? If so, I’ll fork a branch of the docs and add something to this effect to make that clear.

Thanks for the help and all the great work on hugo!

2

Hi @peterk

You are not correct unless the documentation is wrong. Although I agree it would be interesting to know what is the default configuration I doubt it includes keywords.

3

In the mean time: https://github.com/gohugoio/hugoDocs/issues/567

4

@peterk my bad, the default config does have keywords. I tried switching the keyworkd with something else than blog and it works.

There could be a bug involving using Related default’s config (keywords) with a keyword matching the section’s name.

5

This is taken from memory, but I think keywords is expected to be a slice, i.e. keywords: [blog]

6

Tried that as well. It didn’t work until I changed the section’s name.

7

I use related content to display related news or stories.

I do not have anything regarding ‘related’ in my config file.

In my template I do the following:

  {{ $related := .Site.RegularPages.Related . | first 3 }}
  {{ with $related }}
  <div class="related-content">
    <h2>Related content</h2>
    <ul class="article-gallery">
      {{ range . }}
      {{ .Render "gallery" }}
      {{ end }}
    </ul>
  </div>
  {{ end }}

My entire site is on GitHub if you want to dig in.

1 Like
8

Thanks everyone. I’ve done a bit more digging and updated the sample project repo. It looks like everyone was right. @bep, I changed the keyword syntax (keywords: [blog]) and that started working out of the box with zero additional configuration (per the comments from @regis). This also matches @rhewitt’s experience (thanks for sharing, BTW).

Still slightly odd that the incorrect keyword syntax keywords: blog worked after I created an index in the config… Also, I’m curious, is there a reason IncludeNewer is false by default? As a newbie, it’s a little confusing when I expect each post to reference every other post but they only reference posts older than themselves.

Finally, it would be great if there were a shorthand for enabling “includeNewer” without having to specify an index. E.g. if I could just say:

related:
  includeNewer: true

Thoughts welcome. I’m going to respond to the issue kindly created by @regis and see if I can tweak the website docs to make this simpler for other new folks.

Thanks!

9

It was a choice I made … Which mostly boils down to the setting I think I want as the default for my projects. This depends on the context, but in blog/news type of sites, time is a key factor – it would be confusing if 2018 articles suddenly popped up in old archived articles back in 2002 … It is a static site generator, after all. This also becomes a technical thing if you have a big site – if only the new stuff has changed, no need to transfer the complete site.

Documentation sites will typically have a different view.

10

That makes sense, @bep. I think I’m just slightly abusing the feature to promote slightly random, relatively related posts. I’ve found a reasonable solution to this by combining where with .Related to give me the mix I’m looking for:

{{ $related := (where .Site.Pages ".Params.featured" "=" true) | intersect (where .Site.Pages ".Title" "!=" .Title) | union (.Site.RegularPages.Related .) | shuffle | first 10}}

I might still submit a quick PR to make it obvious for newbies how to jump into RelatedContent. It’s a great feature, thanks!

3 Likes