79 lines
7.5 KiB
Plaintext
79 lines
7.5 KiB
Plaintext
<p>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 <a href="https://batsov.com/articles/2021/11/01/switching-to-minimal-mistakes/">switched to using Minimal Mistakes</a> and I had to refresh my knowledge of the subject.</p>
|
||
|
||
<p>Probably few people remember this, but in the early days of Jekyll you had to
|
||
manually generate the Atom feeds you needed. <sup id="fnref:1"><a class="footnote" href="https://batsov.com/articles/2021/11/13/atom-feeds-in-jekyll-redux/#fn:1" rel="footnote">1</a></sup> Back then I’d create a primary
|
||
<code class="language-plaintext highlighter-rouge">atom.xml</code> 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 <code class="language-plaintext highlighter-rouge">atom.xml</code>, add a bit of filtering and end up with feeds named <code class="language-plaintext highlighter-rouge">emacs.xml</code> and <code class="language-plaintext highlighter-rouge">ruby.xml</code>. Life was simple back then, even if it required a bit of extra work.</p>
|
||
|
||
<p>Today, however, we have Jekyll plugins and most people use the <a href="https://github.com/jekyll/jekyll-feed">jekyll-feed</a> plugin, which eliminates the need for all the boilerplate code. Out of the box, the plugin will generate a feed named <code class="language-plaintext highlighter-rouge">feed.xml</code>. 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 <code class="language-plaintext highlighter-rouge">atom.xml</code> name. That’s as simple as adding this snippet to your <code class="language-plaintext highlighter-rouge">_config.yml</code>:</p>
|
||
|
||
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">feed</span><span class="pi">:</span>
|
||
<span class="na">path</span><span class="pi">:</span> <span class="s">atom.xml</span>
|
||
</code></pre></div></div>
|
||
|
||
<p>More interestingly, the plugin can generate additional feeds from your article <code class="language-plaintext highlighter-rouge">Category</code> and <code class="language-plaintext highlighter-rouge">Tags</code> metadata. Here’s how you can create feeds for a specific category:</p>
|
||
|
||
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">feed</span><span class="pi">:</span>
|
||
<span class="na">path</span><span class="pi">:</span> <span class="s">atom.xml</span>
|
||
<span class="na">categories</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s">emacs</span>
|
||
</code></pre></div></div>
|
||
|
||
<p>This will result in the creation of an additional Atom feed named <code class="language-plaintext highlighter-rouge">/feed/emacs.xml</code>.
|
||
Note that for some reason Jekyll doesn’t lowercase category names, so if your category is named Emacs the generated feed will become <code class="language-plaintext highlighter-rouge">/feed/Emacs.xml</code>. I’ve filed a bug about this behavior, as I wasn’t sure if it’s the intended one.</p>
|
||
|
||
<p>You can also generate feeds for all tags like this:</p>
|
||
|
||
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">feed</span><span class="pi">:</span>
|
||
<span class="na">tags</span><span class="pi">:</span> <span class="no">true</span>
|
||
</code></pre></div></div>
|
||
|
||
<p>Now you’ll end up with a bunch of feeds like <code class="language-plaintext highlighter-rouge">/feed/by_tag/emacs.xml</code>, <code class="language-plaintext highlighter-rouge">/feed/by_tag/clojure.xml</code>, etc. Note that as with categories <code class="language-plaintext highlighter-rouge">jekyll-feed</code> won’t lowercase tag names, so “ruby” and “Ruby” will be considered different and will result in the creation of two separate tag feeds.</p>
|
||
|
||
<p>Generating feeds for all tags is probably an overkill for most people, so you can narrow this down to the tags you care about:</p>
|
||
|
||
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">feed</span><span class="pi">:</span>
|
||
<span class="na">tags</span><span class="pi">:</span>
|
||
<span class="na">only</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s">emacs</span>
|
||
<span class="pi">-</span> <span class="s">clojure</span>
|
||
</code></pre></div></div>
|
||
|
||
<p>You can also adjust the path for tag feeds, if you don’t like the default:</p>
|
||
|
||
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">feed</span><span class="pi">:</span>
|
||
<span class="na">tags</span><span class="pi">:</span>
|
||
<span class="na">path</span><span class="pi">:</span> <span class="s2">"</span><span class="s">feed/topics/"</span>
|
||
</code></pre></div></div>
|
||
|
||
<p>You can even shorten it to <code class="language-plaintext highlighter-rouge">feed/</code> if won’t be using category feeds.</p>
|
||
|
||
<p><code class="language-plaintext highlighter-rouge">jekyll-feed</code> 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.</p>
|
||
|
||
<p>After migrating to Minimal Mistakes I managed to mess up the following:</p>
|
||
|
||
<ul>
|
||
<li>I forgot to include the <code class="language-plaintext highlighter-rouge">jekyll-feed</code> settings in my <code class="language-plaintext highlighter-rouge">_config.yml</code>, as I started with a fresh config for the new theme.</li>
|
||
<li>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.</li>
|
||
<li>I kept wondering why <a href="https://batsov.com/feed/emacs.xml">https://batsov.com/feed/emacs.xml</a> results in a 404 error. Eventually I figured out the names were case-sensitive.</li>
|
||
</ul>
|
||
|
||
<p>At least I didn’t forget to update the <code class="language-plaintext highlighter-rouge">atom_feed</code> 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.<sup id="fnref:2"><a class="footnote" href="https://batsov.com/articles/2021/11/13/atom-feeds-in-jekyll-redux/#fn:2" rel="footnote">2</a></sup></p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>That’s all I have for you today. Keep writing!</p>
|
||
|
||
<div class="footnotes">
|
||
<ol>
|
||
<li id="fn:1">
|
||
<p>See my <a href="https://batsov.com/articles/2011/04/24/add-atom-feed-to-jekyll/">old article</a> on the subject. <a class="reversefootnote" href="https://batsov.com/articles/2021/11/13/atom-feeds-in-jekyll-redux/#fnref:1">↩</a></p>
|
||
</li>
|
||
<li id="fn:2">
|
||
<p>Some themes simply hardcode <code class="language-plaintext highlighter-rouge">feed.xml</code> and you have to copy and adjust the layout files if you want to use a different name. <a class="reversefootnote" href="https://batsov.com/articles/2021/11/13/atom-feeds-in-jekyll-redux/#fnref:2">↩</a></p>
|
||
</li>
|
||
</ol>
|
||
</div> |