MkDocs RSS Plugin

1.18.1 · active · verified Thu Apr 16

mkdocs-rss-plugin is an MkDocs plugin that generates RSS and JSON feeds for your documentation site. It leverages your MkDocs site configuration, Git log for commit metadata, and page frontmatter to create rich feed entries. Currently at version 1.18.1, it receives frequent minor updates to improve features, fix bugs, and enhance compatibility with other MkDocs plugins like Material for MkDocs blog.

Common errors

```
ERROR    -  Config value: 'plugins'. Problem: Plugin 'rss' could not be loaded. Error: No module named 'mkdocs_rss_plugin.plugin'
```
cause The `mkdocs-rss-plugin` Python package is not installed in the environment where `mkdocs` is run, or it's misspelled in `mkdocs.yml`.

fix Run `pip install mkdocs-rss-plugin` in your project's virtual environment. Then, ensure `plugins: - rss` is correctly added to your `mkdocs.yml`.
```
ERROR    -  mkdocs_rss_plugin.rss - The 'site_url' setting is not defined in your mkdocs.yml configuration. It is required to generate absolute URLs for the feed.
```
cause The `site_url` configuration option, crucial for generating valid absolute URLs in RSS/JSON feeds, is missing from your `mkdocs.yml`.

fix Add `site_url: https://your-domain.com/` (replacing with your actual site's base URL) at the top level of your `mkdocs.yml` file.
```
Failed to run git command: git rev-list --count HEAD...main. Error: [Errno 2] No such file or directory: 'git'
```
cause The `git` executable is not installed or not accessible in the system's PATH where MkDocs is building, preventing the plugin from using Git history for metadata.

fix Ensure Git is installed on your system and available in the environment's PATH. If using a containerized environment, add Git to the container image.
```
TypeError: 'NoneType' object is not subscriptable (or similar errors when accessing nested plugin configs like `mkdocs_config.plugins.get("material/blog")["some_key"]`)
```
cause This typically occurs when `mkdocs-rss-plugin` tries to access configuration or attributes of another plugin (e.g., Material for MkDocs blog) that is either not enabled, incorrectly configured, or has a different structure than expected.

fix Ensure all integrated plugins (like `material/blog`) are correctly enabled and configured in your `mkdocs.yml`. Update `mkdocs-rss-plugin` to its latest version, as many such integration bugs have been fixed in recent releases.

Warnings

gotcha Absolute URLs in feeds require `site_url` to be defined in `mkdocs.yml`. Without it, generated RSS/JSON feed items will have relative URLs, which are often broken when consumed by external readers.
Fix: Ensure `site_url: https://your-domain.com/` (replace with your actual site URL) is present at the top level of your `mkdocs.yml`.
gotcha Features relying on Git history (e.g., `feed_ttl_days_from_git`, `commit_author`, `pretty_timestamp`) require the `git` executable to be available and the build environment to have a full Git history. Shallow clones (`--depth 1`) or non-Git environments will lead to missing or incorrect metadata.
Fix: Ensure `git` is installed and in your system's PATH. When building in CI/CD, avoid shallow clones or ensure your build job performs a full clone if Git-based features are critical.
breaking Python 3.9 support was temporarily broken in versions 1.17.2-1.17.4 due to a dependency issue, and officially removed with a `requires_python >=3.10` declaration from 1.18.0 onwards.
Fix: Upgrade your Python environment to version 3.10 or newer to ensure full compatibility and receive the latest updates.
gotcha Integration with the Material for MkDocs blog plugin, especially regarding social card URIs and directory URLs, has received several fixes in recent versions (1.17.4, 1.17.8, 1.17.9). Users of this combination might experience subtle URL or metadata issues if not on the latest `mkdocs-rss-plugin` version.
Fix: Keep `mkdocs-rss-plugin` updated to its latest version to benefit from compatibility improvements. Review your Material for MkDocs blog configuration, especially `dir_urls` and social card settings.

Install

pip install mkdocs-rss-plugin Install with pip

Quickstart

To enable the mkdocs-rss-plugin, you need to add it to the `plugins` section of your `mkdocs.yml` configuration file. This example sets up basic RSS and JSON feeds, and configures the plugin to include full page descriptions and filter items from a 'blog' category based on page paths.

mkdocs.yml:
  site_name: My Awesome Docs
  site_url: https://example.com/

  plugins:
    - rss:
        feed_url: feed.xml
        json_feed_url: feed.json
        feed_item_description: true
        categories:
          - blog

docs/index.md:
  # Home page content

docs/blog/post1.md:
  ---
  title: My First Blog Post
  date: 2024-01-15
  author: John Doe
  ---
  This is the content of my first blog post.

# To build the site and generate feeds:
# mkdocs build
# To serve the site locally and see the feeds:
# mkdocs serve

# After running 'mkdocs build', feed.xml and feed.json will be in your site_dir (default: 'site/')

view raw JSON →