General: Adding a rich RSS feed to a Hugo-based Azure Static Website

I posted a while back about moving to using Hugo-based Azure Static Websites for my blog and other simple sites.

One thing I’ve had a number of requests for over the years, is a richer RSS feed for my blog. In particular, while I have a coverImage tag in my front matter, the coverImage didn’t appear in the default RSS feed. I had a few requests about that one. So I set about trying to add a better RSS feed.

I’m using a fork of the Roadster theme. I expected that somewhere, I’d find an rss.xml file. But it was nowhere to be found. In fact, the only file that mentioned RSS was an SEO file. That means it was using some magic hidden default for the RSS file.

You can view the RSS feed by using the URL <site_url>/index.xml.

That appeared, but it also had errors, basically encoding issues from something in my content. So I had to fix that too.

config.toml changes

I found that I needed to make changes to my config.toml. I use that rather than the hugo.toml file, but the concept is the same.

[outputFormats.RSS]
  mediaType = "application/rss+xml"
  baseName = "index"
  isPlainText = true
  notAlternative = true

[outputs]
  home = ["HTML", "RSS"]

[markup]
  [markup.goldmark]
    [markup.goldmark.parser]
      autoHeadingID = true
      [markup.goldmark.renderer]
        unsafe = true
      [markup.goldmark.extensions]
        smart = false

That let me exert control over the encoding. Next, I added an rss.xml file to layouts/_default:

{{- printf "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" | safeHTML }}
<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/">
  <channel>
    <title>{{ .Site.Title }}</title>
    <link>{{ .Site.BaseURL }}</link>
    <description>{{ .Site.Params.description }}</description>
    <language>{{ .Site.Language.Lang }}</language>
    <generator>Hugo -- https://gohugo.io/</generator>

    {{ range first 15 (where .Site.RegularPages "Type" "in" site.Params.mainSections) }}
    <item>
      <title>{{ .Title }}</title>
      <link>{{ .Permalink }}</link>
      <guid>{{ .Permalink }}</guid>
      <pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 AEST" }}</pubDate>

      <description>{{ .Summary | htmlUnescape | plainify }}</description>

      <content:encoded><![CDATA[
        {{ with .Params.coverImage }}
          <img src="{{ . | absURL }}" alt="cover image" /><br />
        {{ end }}
        {{ .Content | htmlUnescape }}
      ]]></content:encoded>
    </item>
    {{ end }}
  </channel>
</rss>

That described how I wanted the feed to look. In particular I wanted to display the contents of the coverImage entry and to show the whole contents of the description.

Displaying the feed details

As well as enhancing the RSS feed, I also wanted to display an icon for the feed. In my case, I wanted to add it to the sidebar as shown in the image above.

I added an icon named RSSFeedLogo.png to my static/images folder.

I then decided to add this as a widget. I created a new file rss_feed.html in layouts/partials/widgets with the following content:

<div class="widget widget-rss">
  <a href="{{ "index.xml" | relURL }}" title="RSS Feed" target="_blank" rel="noopener noreferrer">
    <img src="{{ "images/RSSFeedLogo.png" | relURL }}" alt="RSS Feed" style="width:24px; height:24px;" />
    <span>Subscribe via RSS</span>
  </a>
</div>

That referenced the feed icon and also pointed to the index.xml file for the feed.

Finally, I needed to add the widget to the sidebar. Rather than doing that directly, I added it in the config.toml file:

[Params.sidebar]
home = "right" # Configure layout for home page
list = "right"  # Configure layout for list pages
single = "right" # Configure layout for single pages
widgets = ["course_advert", "ebook_advert", "sdutools_advert", "social", "recent", "rss_feed", "categories"]

And once the site had rebuilt, all was good. I hope this helps someone else.

2025-11-01