Configuration#

To produce a valid RSS feed, the plugin uses:

some global settings from MkDocs configuration
some page attributes
some specific settings to custom behavior or add some optional elements

MkDocs configuration#

Setting	Expected level	Corresponding RSS element
`site_description`	required	`description`
`site_name`	required	`title` and also as `source` URL label for each feed item
`site_url`	required	`link`
----	----	----
`repo_url`	recomended	`docs`
`site_author`	recomended	`managingEditor`
----	----	----
`copyright`	optional	`copyright`
`locale` or `theme/locale` or `theme/language`	optional	`language`

Automatic elements#

Variable / value	Corresponding RSS element
MkDocs build timestamp	optional channel elements `lastBuildDate` and `pubDate`
MkDocs RSS plugin - v1.0.0	optional channel elements `generator`

Page attributes#

Basically, each page is an item element in the RSS feed.

Attribute	Expected level	Corresponding RSS element
`page.canonical_url`	required and optional	mandatory item element `link` and also used as `guid`
`page.meta.title`	required	`title`
`page.meta.description` if present, else extract headlines from the content. See below the item_description_length option.	required	`description`
creation or last update datetime according git log. Can be overridden by dates in page.meta. If not, then it uses MkDcos build date	recomended	`pubDate`
`page.meta.image`	optional	item element `enclosure`. Some HTTP requests can be performed to retrieve remote images length.
`page.meta.authors` or `page.meta.author`. Accepted value types: `str` `list`, `tuple`. To comply with the standard, the page writer is responsible to fill this field following this syntax: `john@doe.com (John Doe)` (read this SO).	optional	`author`
`page.meta.tags` or any tags value (for example `page.meta.categories`...). Accepted value types: `str` `list`.	optional	`category`

Item image (enclosure)#

To add an image to a feed item as enclosure, the page writer is responsible to fill the page.meta.image. The plugin tries to retrieve the image length and mime-type to complete the enclosure tag.

Accepted keys:

image: preferred
illustration: alternative to make it easier to comply with some themes

Accepted values:

remote image URL: must be reachable from the build environment.
relative path to the image: the plugin adds the site_url to the path to ensure that image will be reachable by external feed readers once the site is published.

Examples#

Local image#

mkdocs.yml :

site_url: https://blog.mydomain.com

Page:

---
[...]
image: "featured_images.png"
---

# Page h1 title

Some page text.

Output:

<item>
  [...]
  <title>Page h1 title</title>
  <enclosure url="https://blog.mydomain.com/featured_images.png" type="image/png" length="219753"/>
  [...]
</item>

Remote image#

---
[...]
image: "http://example.com/image.jpg"
---

# Page h1 title

Some page text.

Output:

<item>
  [...]
  <title>Page h1 title</title>
  <enclosure url="http://example.com/image.jpg" type="image/jpg" length="19753"/>
  [...]
</item>

Plugin options#

For a sample see homepage.

Disabling the plugin#

You can use the enabled option to optionally disable this plugin. A possible use case is local development where you might want faster build times. It's recommended to use this option with an environment variable together with a default fallback (introduced in mkdocs v1.2.1, see docs). Example:

plugins:
  - rss:
      enabled: !ENV [MKDOCS_ENABLE_RSS_PLUGIN, True]

Which enables you to disable the plugin locally using:

export MKDOCS_ENABLE_RSS_PLUGIN=false
mkdocs serve

Channel image#

image: URL to image to use as feed illustration.

Default: None.

Example#

plugins:
  - rss:
      image: https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Feed-icon.svg/128px-Feed-icon.svg.png

Output:

<image>
  <url>
    https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Feed-icon.svg/128px-Feed-icon.svg.png
  </url>
  <title>MkDocs RSS Plugin</title>
  <link>https://guts.github.io/mkdocs-rss-plugin/</link>
</image>

Item comments path#

comments_path: path to add to each item URL pointing.

Default: None.

For example, if you're using Material for Mkdocs with comment integration (Disqus or Isso), the comment block is under the div id __comments, so you can set: comments_path: "#__comments" and the output will be:

<item>
  <title>This page title is a perfect clickbait!</title>
  <link>https://website.com/articles/best_article/</link>
  <comments>https://website.com/articles/best_article/#__comments</comments>
  [...]

</item>

Feed length#

length: number of pages to include as feed items (entries).

Default: 20

Feed TTL#

feed_ttl: number of minutes to be cached. Inserted as channel ttl element. See: W3C RSS 2.0 documentation.

Default: 1440 (= 1 day)

Output:

<ttl>1440</ttl>

Item description length#

To fill each item description element:

If this value is set to -1, then the articles' full HTML content will be filled into the description element.
Otherwise, the plugin first tries to retrieve the value of the keyword description from the page metadata.
If the value is non-negative and no description meta is found, then the plugin retrieves the first number of characters of the page content defined by this setting. Retrieved content is the raw markdown converted rougthly into HTML.

abstract_chars_count: number of characters to use as item description.

Default: 150

Item categories#

categories: list of page metadata values to use as RSS item categories.

Default: None.

Example#

In configuration:

- rss:
    categories:
      - tags        # will look into page.meta.tags
      - categories  # will also look into page.meta.categories

In page 1:

---
title: "Lorem Ipsum 1"
tags:
  - tag x
  - tag Y
---

[...]

In page 2

---
title: "Page 2"
categories: ["Release notes", "test"]
---

[...]

Output:

  [...]
  <item>
    <title>Lorem Ipsum 1</title>
    <category>tag x</category>
    <category>tag Y</category>
    [...]
  </item>
  <item>
    <title>Page 2</title>
    <category>Release notes</category>
    <category>test</category>
    [...]
  </item>
  [...]

Dates overriding#

Basically, the plugin aims to retrieve creation and update dates from git log. But sometimes, it does not match the content workflow: markdown generated from sources, .

So, it's possible to use the dates manually specified into the page metadata through the YAML frontmatter.

as_creation: meta tag name to use as creation date. Default to False.
as_update: meta tag name to use as update date. Default to False.
datetime_format: datetime format. Default to "%Y-%m-%d %H:%M".
default_timezone: timezone to use by default to make aware datetimes. Default to UTC. Introduced in version 1.3.0 with PR 142.
default_time: time to use if page contains only a date. Useful to avoid the 'midnight syndrom' or have to specify hour in every single page. Default to None. 24h-clock format is expected: %H:%M. Example: "14:20". Introduced in version 1.4.0 with PR 145.

Example#

For example, in your best_article.md created in 2019, you can write the front-matter like this:

---
title: "This page title is a perfect clickbait!"
authors:
  - "Julien M."
date: "2020-10-22 17:18"
---

# This plugin will change your MkDocs life

Lorem ipsum [...]

So in your mkdocs.yml you will have:

plugins:
  - rss:
      date_from_meta:
        as_creation: "date"
        as_update: false
        datetime_format: "%Y-%m-%d %H:%M"
        default_timezone: Europe/Paris

At the end, into the RSS you will get:

<item>
  <title>This page title is a perfect clickbait!</title>
  <link>https://website.com/articles/best_article/</link>
  <pubDate>Thu, 22 Oct 2020 17:18:00 +0200</pubDate>
  [...]

</item>

Timezone dependencies

The timezones data depends on the Python version used to build: - for Python >= 3.9, it uses the standard library and ships tzdata only on Windows which do not provide such data - for Python < 3.9, pytz is shipped.

Prettified output#

By default, the output file is minified, using Jinja2 strip options and manual work. It's possible to disable it and prettify the output using pretty_print: true.

plugins:
  - rss:
      pretty_print: true

Default: False.

Filter pages#

This adds a match_path option which should be a regex pattern matching the path to your files within the docs_dir. For example if you had a blog under docs/blog where docs_dir is docs you might use:

plugins:
  - rss:
      match_path: "blog/.*"

Since match_path gives you all the power of regular expressions you can have more complex patterns to include multiple directories. For example, to include all pages under both release-notes and articles:

plugins:
  - rss:
      match_path: "(release-notes|articles)/.*"

Default: .*.

URL parameters#

This option allows you to add parameters to the URLs of the RSS feed items. It works as a dictionary of keys/values that is passed to Python urllib.parse.urlencode.
One possible use case is the addition of Urchin Tracking Module (UTM) parameters:

plugins:
  - rss:
      url_parameters:
        utm_source: "documentation"
        utm_medium: "RSS"
        utm_campaign: "feed-syndication"

Will result in:

<?xml version="1.0" encoding="UTF-8" ?>
<rss>
    [...]
    <item>
      [...]
      <link>https://guts.github.io/mkdocs-rss-plugin/?utm_source=documentation&amp;utm_medium=RSS&amp;utm_campaign=feed-syndication</link>
      [...]
    </item>
    [...]
  </channel>
</rss>

Default: None.

Integration#

Reference RSS feeds in HTML meta-tags#

To facilitate the discovery of RSS feeds, it's recomended to add relevant meta-tags into the pages <head>, through template customization in main.html :

{% extends "base.html" %}

{% block extrahead %}
  <!-- RSS Feed -->
  <link rel="alternate" type="application/rss+xml" title="RSS feed of created content" href="{{ config.site_url }}feed_rss_created.xml">
  <link rel="alternate" type="application/rss+xml" title="RSS feed of updated content" href="{{ config.site_url }}feed_rss_updated.xml">
{% endblock %}

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search