{"id":9118,"library":"mkdocs-rss-plugin","title":"MkDocs RSS Plugin","description":"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.","status":"active","version":"1.18.1","language":"en","source_language":"en","source_url":"https://github.com/guts/mkdocs-rss-plugin/","tags":["mkdocs","rss","jsonfeed","documentation","static site generator","blog"],"install":[{"cmd":"pip install mkdocs-rss-plugin","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"This is an MkDocs plugin and requires MkDocs to function.","package":"mkdocs","optional":false},{"reason":"Required for features that extract information from Git history (e.g., commit dates, authors).","package":"git","optional":true},{"reason":"Direct dependency for JSON feed generation; specific version pinned in some releases due to syntax issues.","package":"jsonfeed-util","optional":false}],"imports":[],"quickstart":{"code":"mkdocs.yml:\n  site_name: My Awesome Docs\n  site_url: https://example.com/\n\n  plugins:\n    - rss:\n        feed_url: feed.xml\n        json_feed_url: feed.json\n        feed_item_description: true\n        categories:\n          - blog\n\ndocs/index.md:\n  # Home page content\n\ndocs/blog/post1.md:\n  ---\n  title: My First Blog Post\n  date: 2024-01-15\n  author: John Doe\n  ---\n  This is the content of my first blog post.\n\n# To build the site and generate feeds:\n# mkdocs build\n# To serve the site locally and see the feeds:\n# mkdocs serve\n\n# After running 'mkdocs build', feed.xml and feed.json will be in your site_dir (default: 'site/')","lang":"yaml","description":"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."},"warnings":[{"fix":"Ensure `site_url: https://your-domain.com/` (replace with your actual site URL) is present at the top level of your `mkdocs.yml`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions using Git-dependent features"},{"fix":"Upgrade your Python environment to version 3.10 or newer to ensure full compatibility and receive the latest updates.","message":"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.","severity":"breaking","affected_versions":"1.17.2-1.17.4 (bug) and 1.18.0+ (official requirement)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Prior to 1.17.9, when using Material for MkDocs blog features."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install mkdocs-rss-plugin` in your project's virtual environment. Then, ensure `plugins: - rss` is correctly added to your `mkdocs.yml`.","cause":"The `mkdocs-rss-plugin` Python package is not installed in the environment where `mkdocs` is run, or it's misspelled in `mkdocs.yml`.","error":"ERROR    -  Config value: 'plugins'. Problem: Plugin 'rss' could not be loaded. Error: No module named 'mkdocs_rss_plugin.plugin'"},{"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.","cause":"The `site_url` configuration option, crucial for generating valid absolute URLs in RSS/JSON feeds, is missing from your `mkdocs.yml`.","error":"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."},{"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.","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.","error":"Failed to run git command: git rev-list --count HEAD...main. Error: [Errno 2] No such file or directory: 'git'"},{"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.","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.","error":"TypeError: 'NoneType' object is not subscriptable (or similar errors when accessing nested plugin configs like `mkdocs_config.plugins.get(\"material/blog\")[\"some_key\"]`)"}]}