Atom Feeds in Jekyll: Redux
It’s been over a decade since I’ve started using Jekyll and I’m still struggling with setting up Atom feeds there. Perhaps this happens mostly, because I rarely do any feed-related changes, so I tend to forget how they work exactly. Recently I switched to using Minimal Mistakes and I had to refresh my knowledge of the subject.
Probably few people remember this, but in the early days of Jekyll you had to
manually generate the Atom feeds you needed. 1 Back then I’d create a primary
atom.xml feed including all articles, and occasionally some category feeds that included only a particular
subset of articles (e.g. some of my readers cared only about the stuff I wrote on Emacs or Ruby). I’d copy the code from
atom.xml, add a bit of filtering and end up with feeds named
ruby.xml. Life was simple back then, even if it required a bit of extra work.
Today, however, we have Jekyll plugins and most people use the jekyll-feed plugin, which eliminates the need for all the boilerplate code. Out of the box, the plugin will generate a feed named
feed.xml. That’s fine for most people I guess, but it means I have to (remember to) change the default configuration if I want to preserve my historical
atom.xml name. That’s as simple as adding this snippet to your
feed: path: atom.xml
More interestingly, the plugin can generate additional feeds from your article
Tags metadata. Here’s how you can create feeds for a specific category:
feed: path: atom.xml categories: - emacs
This will result in the creation of an additional Atom feed named
Note that for some reason Jekyll doesn’t lowercase category names, so if your category is named Emacs the generated feed will become
/feed/Emacs.xml. I’ve filed a bug about this behavior, as I wasn’t sure if it’s the intended one.
You can also generate feeds for all tags like this:
feed: tags: true
Now you’ll end up with a bunch of feeds like
/feed/by_tag/clojure.xml, etc. Note that as with categories
jekyll-feed won’t lowercase tag names, so “ruby” and “Ruby” will be considered different and will result in the creation of two separate tag feeds.
Generating feeds for all tags is probably an overkill for most people, so you can narrow this down to the tags you care about:
feed: tags: only: - emacs - clojure
You can also adjust the path for tag feeds, if you don’t like the default:
feed: tags: path: "feed/topics/"
You can even shorten it to
feed/ if won’t be using category feeds.
jekyll-feed has plenty of additional settings, but those are the only ones that I ever needed. Still, as mentioned earlier, I keep forgetting some details about them, which results in silly mistakes from time to time.
After migrating to Minimal Mistakes I managed to mess up the following:
- I forgot to include the
jekyll-feedsettings in my
_config.yml, as I started with a fresh config for the new theme.
- I couldn’t remember how the category feeds were named. As I couldn’t find the info in the project’s README I had to consult the specs to sort this out. I’ll propose some small documentation update to the project maintainers.
- I kept wondering why https://batsov.com/feed/emacs.xml results in a 404 error. Eventually I figured out the names were case-sensitive.
At least I didn’t forget to update the
atom_feed setting for Minimal Mistakes. It’s good that this is a theme where the feed’s path is not hardcoded in the theme’s layouts.2
Anyways, I hope that writing this down will help me remember how to do things properly in the future, and I also hope that I’ll spare some of you from doing the same mistakes.
That’s all I have for you today. Keep writing!
See my old article on the subject. ↩
Some themes simply hardcode
feed.xmland you have to copy and adjust the layout files if you want to use a different name. ↩