Skip to main content

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

Project description

MkDocs RSS plugin

PyPi version badge PyPI - Downloads PyPI - Python Version

codecov Code style: black flake8 Imports: isort pre-commit pre-commit.ci status 📚 Documentation

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_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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_rss_plugin-1.16.0.tar.gz (32.7 kB view details)

Uploaded Source

Built Distribution

mkdocs_rss_plugin-1.16.0-py2.py3-none-any.whl (27.1 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file mkdocs_rss_plugin-1.16.0.tar.gz.

File metadata

  • Download URL: mkdocs_rss_plugin-1.16.0.tar.gz
  • Upload date:
  • Size: 32.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for mkdocs_rss_plugin-1.16.0.tar.gz
Algorithm Hash digest
SHA256 f0e275c933be69a77ee7af92256d88e2969e10c36c5ee1ecdb663a4ea4aa08ea
MD5 5f607cbb503de6899ed5aad1b28a65d8
BLAKE2b-256 c2ac52972ec3b0ee26253b263741dc65ba5d68c67d28ecfe8ef61555e4d9f985

See more details on using hashes here.

File details

Details for the file mkdocs_rss_plugin-1.16.0-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for mkdocs_rss_plugin-1.16.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 be66b11300f1e951d3393ce8da60ca6d730108f731434cc256670b3b8e0cffb3
MD5 1bd04db9dc494864518f401b13056ba6
BLAKE2b-256 a182c588e0d880431f6e89375aa6994ba12ff4d62972441d3c66c63ae8d940ee

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page