RSS and Atom feeds in Jekyll

Episode #18 - May 12, 2016 - 5 minutes

Subscribe to Jekyll Casts

Most blogs have an RSS feed to push content out to readers. There’s two ways we can add a Atom or RSS feed to our Jekyll site: either using Liquid or a Jekyll plugin. Using a plugin is the best way because the code has been tested by hundreds if not thousands of people. However, it’s still useful to learn how to implement RSS using pure Liquid as some Jekyll hosting environments restrict plugins and it’s good to understand how it works.

To begin with we need to understand what a RSS feed actually is. A RSS feed is an XML document which has basic meta data about a site, followed by a list of content items (usually blog posts) which will typically have a title, description, publish date and link.

Here’s an example of a simple RSS feed.

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0">
  <channel>
    <title>RSS Feed Exmple</title>
    <description>RSS is a fascinating technology. The uses for RSS are expanding daily.</description>
    <link>http://www.feedforall.com/industry-solutions.htm</link>
    <item>
      <title>RSS Solutions for Restaurants</title>
      <description>FeedForAll helps Restaurants communicate with customers. Let your customers know the latest specials or events.</description>
      <link>http://www.feedforall.com/restaurant.htm</link>
      <comments>http://www.feedforall.com/forum</comments>
      <pubDate>Tue, 19 Oct 2004 11:09:11 -0400</pubDate>
    </item>
    <item>
      <title>RSS Solutions for Schools and Colleges</title>
      <description>FeedForAll helps Educational Institutions communicate with students about school wide activities, events, and schedules</description>
      <link>http://www.feedforall.com/schools.htm</link>
      <comments>http://www.feedforall.com/forum</comments>
      <pubDate>Tue, 19 Oct 2004 11:09:09 -0400</pubDate>
    </item>
  </channel>
</rss>

When someone subscribes to an RSS feed their RSS aggregator will periodically check this document for new items.

Using Liquid we can output an XML file with this format for our site. First we’ll create /feed.xml with the following content.

---
layout: null
---
<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>Bakery Store - Articles</title>
    <description>Your latest baking news</description>
    <link>{{ site.url }}</link>
    {% for post in site.posts %}
      {% unless post.draft %}
        <item>
          <title>{{ post.title | xml_escape }}</title>
          <description>{{ post.content | xml_escape }}</description>
          <pubDate>{{ post.date | date_to_xmlschema }}</pubDate>
          <link>{{ post.url | prepend: site.url }}</link>
          <guid isPermaLink="true">{{ post.url | prepend: site.url }}</guid>
        </item>
      {% endunless %}
    {% endfor %}
  </channel>
</rss>

This loops over our blog posts and outputs their metadata in an RSS XML format. You might of noticed we’re using a variable site.url which isn’t defined yet. Let’s go ahead and define it in _config.yml.

...
url: http://bakery-store.example.com
...

We just need to add a link to the RSS feed to <head> in _layouts/default.html.

...
<link rel="alternate" type="application/rss+xml" title="Bakery Store RSS" href="/feed.xml">
...

Now when we go to /feed.xml on the live site we see the full feed.

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>Bakery Store - Articles</title>
    <description>Your latest baking news</description>
    <link>http://bakery-store.example.com</link>
        <item>
          <title>Where Did The Cookie Come From</title>
          <description>&lt;p&gt;The chocolate chip cookie was invented by Ruth Graves Wakefield. She owned the Toll House Inn, in Whitman, Massachusetts, a very popular restaurant that featured home cooking in the 1930s. Her cookbook, Toll House Tried and True Recipes, was first published in 1936 by M. Barrows &amp;amp; Company, New York. The 1938 edition of the cookbook was the first to include the recipe “Toll House Chocolate Crunch Cookie” which rapidly became a favorite cookie in American homes.&lt;/p&gt;

&lt;p&gt;Source / Read more &lt;a href=&quot;https://en.wikipedia.org/wiki/Chocolate_chip_cookie&quot;&gt;Wikipedia&lt;/a&gt;&lt;/p&gt;
</description>
          <pubDate>2016-01-02T00:00:00+13:00</pubDate>
          <link>http://bakery-store.example.com/information/2016/01/02/where-did-the-cookie-come-from.html</link>
          <guid isPermaLink="true">http://bakery-store.example.com/information/2016/01/02/where-did-the-cookie-come-from.html</guid>
        </item>
        <item>
          <title>What Is Sour Dough</title>
          <description>&lt;p&gt;Sourdough bread is made by the fermentation of dough using naturally-occurring lactobacilli and yeast. Sourdough bread has a mildly sour taste not present in most breads made with baker’s yeast and better inherent keeping qualities than other breads, due to the lactic acid produced by the lactobacilli.&lt;/p&gt;

&lt;p&gt;Source / Read more &lt;a href=&quot;https://en.wikipedia.org/wiki/Sourdough&quot;&gt;Wikipedia&lt;/a&gt;&lt;/p&gt;
</description>
          <pubDate>2016-01-01T00:00:00+13:00</pubDate>
          <link>http://bakery-store.example.com/information/2016/01/01/what-is-sour-dough.html</link>
          <guid isPermaLink="true">http://bakery-store.example.com/information/2016/01/01/what-is-sour-dough.html</guid>
        </item>    
  </channel>
</rss>

So that’s the Liquid method. Now let’s try using the Jekyll plugin. First we’ll delete /feed.xml so there’s no conflict. Create Gemfile in the root of the site and add the jekyll and jekyll-feed gem.

source 'https://rubygems.org'

gem 'jekyll'

group :jekyll_plugins do
  gem 'jekyll-feed'
end

Next we’ll replace the <link> we added to the <head> in the last section with a Liquid tag from the plugin.

...
{% feed_meta %}
...

The last step is to run bundle install on the command line to install jekyll-feed. When we run jekyll now we need to run with bundle exec to include the gem.

bundle exec jekyll serve

Now when we navigate to /feed.xml on the live site we get a feed of our posts.

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <generator uri="http://jekyllrb.com" version="3.1.2">Jekyll</generator>
  <link href="http://bakery-store.example.com/feed.xml" rel="self" type="application/atom+xml" />
  <link href="http://bakery-store.example.com/" rel="alternate" type="text/html" />
  <updated>2016-05-13T16:22:08+12:00</updated>
  <id>http://bakery-store.example.com/</id>
  <entry>
    <title>Where Did The Cookie Come From</title>
    <link href="http://bakery-store.example.com/information/2016/01/02/where-did-the-cookie-come-from.html" rel="alternate" type="text/html" title="Where Did The Cookie Come From" />
    <published>2016-01-02T00:00:00+13:00</published>
    <updated>2016-01-02T00:00:00+13:00</updated>
    <id>http://bakery-store.example.com/information/2016/01/02/where-did-the-cookie-come-from</id>
    <content type="html" xml:base="http://bakery-store.example.com/information/2016/01/02/where-did-the-cookie-come-from.html">&lt;p&gt;The chocolate chip cookie was invented by Ruth Graves Wakefield. She owned the Toll House Inn, in Whitman, Massachusetts, a very popular restaurant that featured home cooking in the 1930s. Her cookbook, Toll House Tried and True Recipes, was first published in 1936 by M. Barrows &amp;amp; Company, New York. The 1938 edition of the cookbook was the first to include the recipe “Toll House Chocolate Crunch Cookie” which rapidly became a favorite cookie in American homes.&lt;/p&gt;

&lt;p&gt;Source / Read more &lt;a href=&quot;https://en.wikipedia.org/wiki/Chocolate_chip_cookie&quot;&gt;Wikipedia&lt;/a&gt;&lt;/p&gt;
    </content>
    <category term="Information" />
    <summary>The chocolate chip cookie was invented by Ruth Graves Wakefield. She owned the Toll House Inn, in Whitman, Massachusetts, a very popular restaurant that featured home cooking in the 1930s. Her cookbook, Toll House Tried and True Recipes, was first published in 1936 by M. Barrows &amp;amp; Company, New York. The 1938 edition of the cookbook was the first to include the recipe “Toll House Chocolate Crunch Cookie” which rapidly became a favorite cookie in American homes.</summary>
  </entry>
  <entry>
    <title>What Is Sour Dough</title>
    <link href="http://bakery-store.example.com/information/2016/01/01/what-is-sour-dough.html" rel="alternate" type="text/html" title="What Is Sour Dough" />
    <published>2016-01-01T00:00:00+13:00</published>
    <updated>2016-01-01T00:00:00+13:00</updated>
    <id>http://bakery-store.example.com/information/2016/01/01/what-is-sour-dough</id>
    <content type="html" xml:base="http://bakery-store.example.com/information/2016/01/01/what-is-sour-dough.html">&lt;p&gt;Sourdough bread is made by the fermentation of dough using naturally-occurring lactobacilli and yeast. Sourdough bread has a mildly sour taste not present in most breads made with baker’s yeast and better inherent keeping qualities than other breads, due to the lactic acid produced by the lactobacilli.&lt;/p&gt;

&lt;p&gt;Source / Read more &lt;a href=&quot;https://en.wikipedia.org/wiki/Sourdough&quot;&gt;Wikipedia&lt;/a&gt;&lt;/p&gt;
    </content>
    <category term="Information" />
    <summary>Sourdough bread is made by the fermentation of dough using naturally-occurring lactobacilli and yeast. Sourdough bread has a mildly sour taste not present in most breads made with baker’s yeast and better inherent keeping qualities than other breads, due to the lactic acid produced by the lactobacilli.</summary>
  </entry>
</feed>

You can customize all the fields and add extra metadata such as an author. Check out the jekyll-feed GitHub repository for more information.

Subscribe to Jekyll Casts