A Jekyll plugin to generate an Atom (RSS-like) feed of your Jekyll posts
Add this line to your site's Gemfile:
gem 'jekyll-feed'
And then add this line to your site's _config.yml
:
plugins:
- jekyll-feed
gems
key instead of plugins
.
The plugin will automatically generate an Atom feed at /feed.xml
.
The plugin will automatically use any of the following configuration variables, if they are present in your site's _config.yml
file.
title
orname
- The title of the site, e.g., "My awesome site"description
- A longer description of what your site is about, e.g., "Where I blog about Jekyll and other awesome things"url
- The URL to your site, e.g.,https://example.com
. If none is provided, the plugin will try to usesite.github.url
.author
- Global author information (see below)
Do you already have an existing feed someplace other than /feed.xml
, but are on a host like GitHub Pages that doesn't support machine-friendly redirects? If you simply swap out jekyll-feed
for your existing template, your existing subscribers won't continue to get updates. Instead, you can specify a non-default path via your site's config.
feed:
path: atom.xml
To note, you shouldn't have to do this unless you already have a feed you're using, and you can't or wish not to redirect existing subscribers.
The plugin will use the following post metadata, automatically generated by Jekyll, which you can override via a post's YAML front matter:
date
title
excerpt
id
category
tags
Additionally, the plugin will use the following values, if present in a post's YAML front matter:
-
image
- URL of an image that is representative of the post (can also be passed asimage.path
) -
author
- The author of the post, e.g., "Dr. Jekyll". If none is given, feed readers will look to the feed author as defined in_config.yml
. Like the feed author, this can also be an object or a reference to an author in_data/authors.yml
(see below).
TL;DR: In most cases, put author: [your name]
in the document's front matter, for sites with multiple authors. If you need something more complicated, read on.
There are several ways to convey author-specific information. Author information is found in the following order of priority:
- An
author
object, in the documents's front matter, e.g.:
author:
twitter: benbalter
- An
author
object, in the site's_config.yml
, e.g.:
author:
twitter: benbalter
site.data.authors[author]
, if an author is specified in the document's front matter, and a corresponding key exists insite.data.authors
. E.g., you have the following in the document's front matter:
author: benbalter
And you have the following in _data/authors.yml
:
benbalter:
picture: /img/benbalter.png
twitter: jekyllrb
potus:
picture: /img/potus.png
twitter: whitehouse
In the above example, the author benbalter
's Twitter handle will be resolved to @jekyllrb
. This allows you to centralize author information in a single _data/authors
file for site with many authors that require more than just the author's username.
Pro-tip: If authors
is present in the document's front matter as an array (and author
is not), the plugin will use the first author listed.
- An author in the document's front matter (the simplest way), e.g.:
author: benbalter
- An author in the site's
_config.yml
, e.g.:
author: benbalter
The plugin exposes a helper tag to expose the appropriate meta tags to support automated discovery of your feed. Simply place {% feed_meta %}
someplace in your template's <head>
section, to output the necessary metadata.
The plugin uses Jekyll's smartify
filter for processing the site title and post titles. This will translate plain ASCII punctuation into "smart" typographic punctuation. This will not render or strip any Markdown you may be using in a title.
Jekyll's smartify
filter uses kramdown as a processor. Accordingly, if you do not want "smart" typographic punctuation, disabling them in kramdown in your _config.yml
will disable them in your feed. For example:
kramdown:
smart_quotes: apos,apos,quot,quot
typographic_symbols: {hellip: ...}
Want to style what your feed looks like in the browser? Simply add an XSLT at /feed.xslt.xml
and Jekyll Feed will link to the stylesheet.
Great question. In short, Atom is a better format. Think of it like RSS 3.0. For more information, see this discussion on why we chose Atom over RSS 2.0.
Jekyll Feed can generate feeds for each category. Simply define which categories you'd like feeds for in your config:
feed:
categories:
- news
- updates
Jekyll Feed can generate feeds for collections other than the Posts collection. This works best for chronological collections (e.g., collections with dates in the filenames). Simply define which collections you'd like feeds for in your config:
feed:
collections:
- changes
By default, collection feeds will be outputted to /feed/<COLLECTION>.xml
. If you'd like to customize the output path, specify a collection's custom path as follows:
feed:
collections:
changes:
path: "/changes.xml"
Finally, collections can also have category feeds which are outputted as /feed/<COLLECTION>/<CATEGORY>.xml
. Specify categories like so:
feed:
collections:
changes:
path: "/changes.xml"
categories:
- news
- updates
Optional flag excerpt_only
allows you to exclude post content from the Atom feed. Default value is false
for backward compatibility.
When in config.yml
is true
than all posts in feed will be without <content>
tags.
feed:
excerpt_only: true
The same flag can be used directly in post file. It will be disable <content>
tag for selected post.
Settings in post file has higher priority than in config file.
- Fork it (https://github.com/jekyll/jekyll-feed/fork)
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request