blogging liquid plugins

Introduction

Most blogs have an RSS or Atom feed to notify readers of new content on the site. 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 thousands of people. However, it’s still useful to look at implementing RSS using pure Liquid to understand how it works.

What is an RSS Feed?

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 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

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: none
---
<?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 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
...

Finally, we 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>

jekyll-feed plugin

Let’s go through using the jekyll-feed plugin instead of the pure Liquid approach. 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

Instead of adding a <link> to RSS in the layout like the previous section, we can use a Liquid tag from the plugin:

...
{% feed_meta %}
...

The last step is to run bundle install on the command line to install jekyll-feed and run jekyll with bundle exec:

bundle exec jekyll serve

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.