Registry / web-framework / mkdocs-rss-plugin

mkdocs-rss-plugin

library1.18.1pypypiunverified

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.

web-framework serialization

pip install mkdocs-rss-plugin

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · MKDOCS-RSS-PLUGIN

mkdocs-rss-plugin

web-frameworkpythonv1.18.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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/')

Debug

Known issues

gotchaAbsolute 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`.

affects: All versions

gotchaFeatures 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.

affects: All versions using Git-dependent features

breakingPython 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.

affects: 1.17.2-1.17.4 (bug) and 1.18.0+ (official requirement)

gotchaIntegration 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.

affects: Prior to 1.17.9, when using Material for MkDocs blog features.

Errors

Common errors & fixes

ERROR - Config value: 'plugins'. Problem: Plugin 'rss' could not be loaded. Error: No module named 'mkdocs_rss_plugin.plugin'

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.

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'

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"]`)

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.

Upgrade

Version history

1.18.1latest on PyPI · released Apr 10, 2026

Audit

Dependencies

mkdocsrequiredThis is an MkDocs plugin and requires MkDocs to function.

gitoptionalRequired for features that extract information from Git history (e.g., commit dates, authors).

jsonfeed-utilrequiredDirect dependency for JSON feed generation; specific version pinned in some releases due to syntax issues.