After a 4 year hiatus, I’m finally coming back around to this blog and doing some cleaning before writing again. Part of that cleaning includes making sure the RSS feed works as expected. To do so, it needs to check off the following:

• Provide valid RSS content
• Include the posts’ contents so they can easily be read with RSS readers
• Exclude pages that are not posts

The first box is ticked by default thanks to Hugo’s RSS generator

Task 1: Including the post’s contents

Looking at PaperMod’s RSS layout, I noticed the following code:

{{- if and site.Params.ShowFullTextinRSS .Content }}
    <content:encoded>{{ (printf "<![CDATA[%s]]>" .Content) | safeHTML }}</content:encoded>
{{- end }}

This might’ve been added some time in the 4 years since I started this blog and seems to solve all of our problems. One update to our site’s config and voilà, the RSS feed’s XML includes our posts’ content in it!

One task down, one to go!

Task 2: Excluding specific pages

The easy way

As pointed out on Hugo’s Discourse there is a straightforward way to generate an RSS feed only for blog posts:

1. Update the output section of your site’s config file so it does not include RSS

[...]

[output]
- home = ["HTML", "RSS", "JSON"]
+ home = ["HTML", "JSON"]

[...]

2. Add an _index.md file to your /posts subfolder with the following front matter:

+++
title = "Posts"
outputs = ["HTML", "RSS"]
+++

3. We now have an RSS feed at https://sunbro.dev/posts/index.xml!

… but there’s one problem: this breaks the feed for anyone already subscribed to the current feed at https://sunbro.dev/index.xml. That URL now 404s.

The “correct” way

Now that we know we want to preserve the current /index.xml let’s give ourselves a way to exclude certain pages from it. Let’s add a new entry on to our pages’ config: RSSExclude. You should add it to all the pages you want to exclude from the RSS feed.

For example in my projects.md that I want to exclude I added:

+++
title = "Projects"
[...]
RSSExclude = true
+++

Now, let’s customise PaperMod’s index.xml layout to take it into account. Copy the theme’s file into your /layouts/_default/ and edit it as follows:

- {{- if and (ne .Layout `search`) (ne .Layout `archives`) }}
+ {{- if ne .Params.RssExclude true }}
    <item>
        [...]
    </item>
{{- end }}

Instead of only excluding pages with the search or archives layouts we now exclude all pages where RSSExclude is true.

Task two, check!

Conclusion

I’m happy to see this was much easier than I thought. Although I wish PaperMod natively supported excluding pages from the RSS feed, this has only motivated me to tweak the theme’s layouts even further in the future.

At the time of writing this post, this website uses Hugo and the Terminal theme by panr. I really like the way this theme handles content and Markdown integration, but there is no native support for videos. This is probably due to the fact that there currently is no way to embed videos in Markdown files, unlike images for example.

This problem reared its head when I was writing my first Pokémon Emerald romhack post. At the time, I planned to use GIFs to illustrate the changes made to the game. However, I quickly realised that GIFs take up a lot of memory and can take quite long to load for readers, contrary to videos, MP4 in our case, which are up to 10 times smaller !

$ du -h static/captures/birch_speech_original.gif
3.1M static/captures/birch_speech_original.gif

$ du -h static/captures/birch_speech_original.mp4
332K static/captures/birch_speech_original.mp4

Solution

The answer to our solution comes in the form of Hugo “shortcodes”. Shortcodes are a way to bridge the gap from Markdown to HTML. Therefore, we can use one to handle integrating videos in our posts’ Markdown files.

To get started create a shortcodes sub-directory in your layouts folder. Once that is done create a video.html file in layouts/shortcodes/. The shortcode’s code is as follows:

<video autoplay loop muted playsinline aria-label='{{ .Get "label"}}' style="width: 100%; height: auto;">
    {{ with .Get "mp4" }}<source src="{{ . }}" type="video/mp4">{{ end }}
    {{ with .Get "webm" }}<source src="{{ . }}" type="video/webm">{{ end }}
    <p> Your browser does not support video. </p>
</video>

The syntax is explicit enough to get a basic grasp of how it works. Our shortcode takes three possible parameters: label, mp4, and webm. If label is defined, its contents become the aria-label of the video HTML element. If mp4 or webm is defined, their contents become the source for the video element.

The rest of the shortcode is plain HTML, with inlined style to make it “responsive” and readable on mobile devices.

Using the shortcode in a post’s Markdown file goes like this:

{{< video label="this is a label" mp4="/path/to/video.mp4" >}}

I hope this helps you if you encounter the same problem, good luck!