Add an RSS Feed to Your Hugo Blog

Janne Kemppainen | May 9, 2021

RSS might not be as fashionable as it was many years ago, but it’s still a great way to easily stay up to date with your favorite sites. If you have a Hugo site, you probably already have a working RSS feed. You just might not know about it!

Hugo comes with a built-in RSS Template that generates the necessary RSS XML for you. Often, this internal template is good enough, and you just need to include the feed links in the correct places.

How RSS works

But before we go to the Hugo specific part I think it’s important that you know how RSS actually works.

RSS stands for Really Simple Syndication, and it’s a way to give a programmatic access to the updates on a website. It uses a standardized format that news aggregators can easily read. The feed is simply an XML file that lists the recent content and the feed consumers periodically poll this file to stay up to date with the changes.

When someone subscribes to your blog feed with an RSS reader they save the feed URL in their reader application. But how do they find the correct URL?

There are two ways that you can share your feed.

The first way is to make the feed URL visible on each page. Users can then copy the link and paste it to their feed reader. You should probably use the orange RSS logo in your link since it’s so widely known.

The second way is to reference the feed in the <head> section of the web page. Add a <link> element that looks something like this:

<link rel="alternate" type="application/rss+xml" href="https://example.com/index.xml" title="My Site">

Now a browser plugin can detect it and let the user add it to their list of feeds. This is really handy for the user since they don’t need to copy and paste the URL around.

Add RSS to your Hugo site

The first thing you need to do is to check your project configuration. By default, Hugo will include an unlimited number of pages, but you can limit this to a smaller number with the rssLimit option. This, and some other options, can be configured in the config.toml file:

rssLimit = 20
copyright = "2021 Janne Kemppainen All rights reserved"
languageCode = "en-us"

[author]
	name = "Janne Kemppainen"
	email = "[email protected]"

Next, you need to add the following snippet inside the <head> tags of theme’s head partial (layouts/partials/head.html):

{{ range .AlternativeOutputFormats -}}
    {{ printf `<link rel="%s" type="%s" href="%s" title="%s" />` .Rel .MediaType.Type .Permalink $.Site.Title | safeHTML }}
{{ end -}}

(You can find this snippet from the Hugo docs.)

This lists the alternative output formats as links on each applicable page. But what does that mean?

By default, single pages output only HTML. This makes sense since it wouldn’t be that useful to subscribe to a feed that would always have only one page.

However, home, section, taxonomy, and term pages also output RSS. The snippet adds the corresponding feed as a reference to the current page. If a user goes to example.com/blog, they can subscribe to all content under that path with their feed reader. Similarly, they could go to example.com/categories/hugo to receive only Hugo-related updates.

If you want to make the existence of the feed more obvious you can add a visible link somewhere on your site.

If you’re using a third-party theme then you should check the theme documentation and/or the code to see if they have added RSS support. It is possible to override parts of a theme by copying the files to the same path in your site layout directory but consider opening an issue or even a pull request to add RSS support if it is missing. That should save you from trouble when you update to a newer version of the teme.

Customization

You can find the internal RSS template from GitHub. If you want to customize your feed, then that should probably be your starting point. You can use all of that Go HTML templating that we’ve been going through in this blog series to customize the output.

The default template includes only the summary of each blog post. If you’d like to create a full-text feed then you’d have to change this line

<description>{{ .Summary | html }}</description>

to this

<description>{{ .Content | html }}</description>

The edited file needs to be saved as layouts/_default/rss.xml so that it will override the default feed. You could also create different templates for different sections or page types. Check the correct lookup order from the official Hugo documentation.

List available RSS feeds

If you click the small RSS icon in the top navigation bar on my site you’ll see the list of available RSS feeds on this site.

That page is generated by this template in my theme, saved as layouts/_default/rss.html:

{{ define "main" }}
<div class="container has-background-white">
  <section class="section">
    {{ with .Title }}
    <h1 class="title is-2">{{ . }}</h1>
    {{ end }}
    <div class="content">
      {{ with .Content }}{{ . }}{{ end }} 
      {{ range $taxonomyName, $taxonomy := .Site.Taxonomies }} 
      {{ if ne $taxonomyName "tags" }}
      <h2>{{ $taxonomyName | title }}</h2>
      <ul>
        {{ range $key, $value := $taxonomy }}
        {{ with $value.Page.OutputFormats.Get "rss" }}
        <li><a href="{{ .Permalink }}">{{ $value.Page.Title }}</a></li>
        {{ end }}
        {{ end }}
      </ul>
      {{ end }} 
      {{ end }}
    </div>
  </section>
</div>
{{ end }}

Then, my RSS page contents in content/rss.md look something like this:

---
title: "RSS Feeds"
layout: rss
---

Text content to be shown on the page.

The RSS page Markdown file sets the correct page template with the layout setting. It loops through all taxonomies, excluding "tags" with the if statement. Then, each taxonomy key is looped and a link to the corresponding feed is added to the list.

This way the user can choose to subscribe only to the topics they are interested in, for example Python. The page also lists my blog series automatically, so you could subscribe to this Blog with Hugo series.

I’m using the Bulma CSS framework, so the class names are specific to it, in case you’re wondering.

Conclusion

Adding RSS is quite easy, especially if you’re happy with the default output format. While you’re at it, why not subscribe to my feed to stay up to date with the newest updates?

Share your comments on Twitter if you have any, and see you in the next post!