mkdocs-rss-plugin 1.11.1

MkDocs plugin which generates a static RSS feed using git log and page.meta.

MkDocs RSS plugin

A plugin for MkDocs, the static site generator, which creates RSS 2.0 feeds using the creation and modification dates from git log and page metadata (YAML frontmatter).

Installation

pip install mkdocs-rss-plugin

Usage

Minimal mkdocs.yml configuration:

site_description: required. Used as feed mandatory channel description.
site_name: required. Used as feed mandatory channel title and items source URL label.
site_url: required. Used to build feed items URLs.

Minimal plugin option:

plugins:
  - rss

Full options:

plugins:
  - rss:
      abstract_chars_count: 160  # -1 for full content
      abstract_delimiter: <!-- more -->
      categories:
        - tags
      comments_path: "#__comments"
      date_from_meta:
        as_creation: "date"
        as_update: false
        datetime_format: "%Y-%m-%d %H:%M"
        default_timezone: Europe/Paris
        default_time: "09:30"
      enabled: true
      feed_ttl: 1440
      image: https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Feed-icon.svg/128px-Feed-icon.svg.png
      length: 20
      pretty_print: false
      match_path: ".*"
      url_parameters:
        utm_source: "documentation"
        utm_medium: "RSS"
        utm_campaign: "feed-syndication"
      use_git: true
      use_material_social_cards: true

For further information, see the user documentation.

Following initiative from the author of Material for MkDocs, this plugin provides its own JSON schema to validate configuration: source - documentation.

Development

Clone the repository:

# install development dependencies
python -m pip install -U -r requirements/development.txt
# alternatively: pip install -e .[dev]

# install project as editable
python -m pip install -e .

# install git hooks
pre-commit install

Then follow the contribution guidelines.

Run the tests

# install development dependencies
python -m pip install -U -r requirements/testing.txt
# alternatively: pip install -e .[test]

# run tests
pytest

Build the documentation

# install dependencies for documentation
python -m pip install -U -r requirements/documentation.txt
# alternatively: pip install -e .[doc]

# build the documentation
mkdocs build

Release workflow

1. Fill the CHANGELOG.md
2. Change the version number in __about__.py
3. Apply a git tag with the relevant version: git tag -a 0.3.0 {git commit hash} -m "New awesome feature"
4. Push tag to main branch: git push origin 0.3.0