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 |
Plugin options#
For a sample see homepage.
Channel image#
image
: URL to image to use as feed illustration.
Default: None
.
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>
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, the plugin first tries to retrieve the value of the keyword description
from the page metadata.
If the page has no meta, 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
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".
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"
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 -0000</pubDate>
[...]
</item>
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: .*
.
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 %}