README.md

MkDocs RSS plugin

A plugin for MkDocs, the static site generator, which creates RSS 2.0 and JSON Feed 1.1 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" # means from page.meta.date
        as_update: "git" # means from git log
        datetime_format: "%Y-%m-%d %H:%M"
        default_time: "09:30"
        default_timezone: Europe/Paris
      enabled: true
      feed_description: "My custom feed description"  # MkDocs site_description: will be used if this key is not present
      feeds_filenames:
        json_created: feed_json_created.json
        json_updated: feed_json_updated.json
        rss_created: feed_rss_created.xml
        rss_updated: feed_rss_updated.xml
      feed_title: "My custom feed title"  # MkDocs site_name: will be used if this key is not present
      feed_ttl: 1440
      image: https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Feed-icon.svg/128px-Feed-icon.svg.png
      json_feed_enabled: true
      length: 20
      match_path: ".*"
      pretty_print: false
      rss_feed_enabled: true
      url_parameters:
        utm_source: "documentation"
        utm_medium: "RSS"
        utm_campaign: "feed-syndication"
      use_git: true
      use_material_blog: 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