Customizing Hugo / Blogdown RSS Templates

Blogdown makes it easy to create Hugo blogs or personal websites, and it is becoming more and more popular in the R community. Once the blog is created, people might want to submit their blogs’ RSS feeds to R-bloggers. But before that can happen, one must modify the RSS template to meet the requirements of RSS submission.

Due to my successful experience in creating a new Jekyll RSS template for my blog, I thought it would be easy to customize the RSS template of Hugo blogs to make it suitable for R-bloggers. I was WRONG. Hugo has stricter rules for modifying RSS templates¹, and it took me a while to figure out how to modify the category/tag RSS templates.

By default, Hugo generates different RSS feeds for each section and taxonomy². I will write about how to modify a subset of them to create category- or tag-specific RSS feeds for R-bloggers, i.e, making the <description> field of the RSS feed display full content, rather than an excerpt, of a post.

Overwriting the default RSS Template

You won’t find any RSS template files shipped with Hugo themes (at least Hugo Acadimic theme doesn’t). RSS files (index.xml) will be generated (in public/) according to the default RSS template.

To override the default RSS template without touching the theme template,

1. Copy the default RSS template

2. Change <description>{% raw %}{{ .Summary | html }}{% endraw %}</description> to <description>{% raw %}{{ .Content | html }}{% endraw %}</description>

3. Create subdirectories in layouts/ and save the RSS template files (name them rss.xml) in them (one for each subdirectory).

Putting RSS templates in different subdirectories will have effects on different kind of RSS feeds. The file name (e.g. rss.xml) of the template also matters and can’t be arbitrary. Read Hugo’s documentation on Lookup Order for RSS Templates for details³.

An Example: Hugo Acadimic Theme

I use Hugo Acadimic theme as an example to set two kinds of RSS templates:

1. A template that causes RSS feeds under every category to display full content of the posts

   • Browse RSS feed
   • GitHub source: layouts/categories/rss.xml

2. A template with <category> fields to capture all post tags

   • Browse RSS feed
   • GitHub source: layouts/post/rss.xml

Directory Tree

Below is the directory structure (simplified) after adding RSS templates to Hugo Acadimic theme. I added and modified rss.xml in /layouts/post/ and /layouts/categories/. Then /docs/post/index.xml and /docs/categories/r/index.xml get generated according to /layouts/post/rss.xml and /layouts/categories/rss.xml, respectively.

Note that /docs is /public by default, when publishDir = "docs" is not set in /config.toml. Using /docs allows me to publish Hugo blog on GitHub Pages. DO NOT add publishDir = "docs" in config.toml if you’re serving the site with netlify.

 1/
 2├── index.Rmd
 3├── Hugo-RSS.Rproj
 4├── config.toml
 5├── content/
 6│   ├── home/
 7│   └── post/
 8│       ├── 2015-07-23-r-rmarkdown.html
 9│       └── 2015-07-23-r-rmarkdown.Rmd
10│
11├── layouts/
12│   ├── post/
13│   │   └── rss.xml          # Add/Modify RSS template here
14│   └── categories/
15│       └── rss.xml          # Add/Modify RSS template here
16│
17├── docs/                    # change 'public' to 'docs' in /config.toml
18│   ├── index.html
19│   ├── index.xml
20│   ├── home/
21│   ├── post/
22│   │   ├── index.xml        # set in '/layouts/post/rss.xml' 
23│   │   ├── index.html
24│   │   ├── 2015-07-23-r-rmarkdown/
25│   │   └── 2015-07-23-r-rmarkdown_files/
26│   └── categories/
27│       └── r/
28│           ├── index.xml    # set in '/layouts/categories/rss.xml'      
29│           └── index.html
30└── themes/
31    └── hugo-academic/

Source Code

You can check out the complete directory at GitHub and the web page generated from this repo.