Setting up an RSS feed for a Hugo blog using the PaperMod Theme

Supporting an RSS feed on your blog is an easy way of keeping those who follow you up to date on your latest posts. Hugo, a popular static site generator, comes with a default RSS 2.0 template which PaperMod, a popular Hugo theme maintained by adityatelange, builds upon further.

In order to add an RSS feed that’s automatically generated as part of the build step of your website, you will need to potentially do the following steps in your Hugo configuration file:

• Ensure ‘RSS’ is listed as an ‘output’ format
• Add the RSS feed icon to your home page
• Enable full content support in the generated RSS XML file

All of the above steps are optional depending on your desired setup. For instance, you may not want to add the RSS feed icon to your home page, and not doing so will still result in a RSS XML file being generated as part of Hugo’s build process.

Ensure ‘RSS’ is listed in the ‘output’ formats

RSS is one of the built-in formats supported by Hugo, and by default RSS is added to a Hugo Page that’s of Kind ‘home’ as seen in Hugo’s documentation.

However, in the PaperMod theme, if you are using the built-in search functionality you’ll need to double check that it’s part of the list of output formats, as an override to the default output formats would have been necessary. The following snippet of code was taken from the PaperMod configuration documentation, which can be found here:

outputs:
  home:
      - HTML
      - RSS
      - JSON

As long as ‘RSS’ is present, either as part of the default output configuration or as part of one configured by you, an index.xml file will be generated in the compiled site by Hugo as part of the build process.

Add the RSS feed icon to your home page

PaperMod supports adding the RSS feed icon as a social icon. This is easily added to your blog home page by adding the following to your configuration file:

params:
  socialIcons:
    - name: "rss"
      url: "<URL of your website>/index.xml"

If you want to locally test the generated XML for the RSS feed, replace <URL of your website> with the URL of your locally running Hugo server. Clicking on the RSS icon that appears on the page will open a new tab containing the generated XML, which you can then validate using an RSS feed validator (such as the one W3C provides for free) to confirm that it would be read successfully by RSS readers.

Enabling full content support in the generated RSS XML file

It should be noted that the default behaviour at the time of writing will result in the generated XML only rendering a summary of the posts.

This means that those who receive a notification of a new post will need to click through to your website, out of their RSS reader.

This, while a small inconvenience, can be a barrier to additional readers of the post you’ve put a lot of work and thought into! So how can we get around this so that the full content of your post is rendered in the RSS reader?

There are 2 approaches:

• Enable the ShowFullTextinRSS configuration property that is specific to the PaperMod theme
• Fork the PaperMod theme, modify the underlying template code, and install the modified theme as a submodule in your project, replacing the original PaperMod installation.

Enable the ShowFullTextinRSS configuration property

This is added under the params property:

params:
  ShowFullTextinRSS: true

and will result in the generated XML now including a <content:encoded> block that contains the encoded content of the entire post.

Note: While the <content:encoded> block would ideally be where the content of the post should live within the generated XML, it may not be picked up properly by RSS readers such as Feedly, which appears to derive the content of the post only from the <description> block of the generated XML. Which brings us to the less convenient alternative…

Fork the theme Git repository, modify the code, install the Git submodule

Assuming that you’ve forked the PaperMod repository already, and have cloned the forked repository locally, the code that you will want to modify is the <description> template logic in the following code (permalink here for the specific line as the code evolves):

<item>
  <title>{{ .Title }}</title>
  <link>{{ .Permalink }}</link>
  <pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
  {{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}}
  <guid>{{ .Permalink }}</guid>
  <description>{{ with .Description | html }}{{ . }}{{ else }}{{ .Summary | html }}{{ end -}}</description>
  {{- if .Site.Params.ShowFullTextinRSS }}
  <content:encoded>{{ (printf "<![CDATA[%s]]>" .Content) | safeHTML }}</content:encoded>
  {{- end }}
</item>

As outlined by Sophia Brandt in a blog post titled “How to create a full text RSS feed for Hugo”:

The RSS 2.0 spec says that the description element can contain “the item’s full content or a summary of its contents, a decision entirely at the discretion of the publisher.” (source)

and she goes on to say that you want to modify the <description> block to reference the .Content, not the .Summary. This means that this specific line:

<description>{{ with .Description | html }}{{ . }}{{ else }}{{ .Summary | html }}{{ end -}}</description>

should become:

<description>{{ with .Description | html }}{{ . }}{{ else }}{{ .Content | html }}{{ end -}}</description>

Once you’ve made that change, committed it, and have it pushed to your forked repository, you can install it on your Hugo blog by:

1. Modifying the .gitmodules file to reference the URL of your forked project as the URL of the package:

[submodule "themes/PaperMod"]
	path = themes/PaperMod
	url = https://github.com/<your github username>/hugo-PaperMod.git

Run git submodule sync

Delete the old themes/PaperMod folder within your blog

Run git submodule update --remote --merge

This ensures that the submodules are pointed to the most recent commit hash on your repository and installs that version

If you’re interested in digging deeper into git submodules (including how to integrate a submodule back into your project), you can read more in this helpful guide by Nicola Paolucci of Atlassian.