guts / mkdocs-rss-plugin

MkDocs plugin to generate a RSS feeds for created and updated pages, using git log and YAML frontmatter (page.meta).

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

mkdocs-rss-plugin's Issues

Feed for updated content is broken

Reported by email

change feed url?

I'm migrating my blog from something else to mkdocs and my existing feed URL is simply feed.xml.
Since I'm hosting on Github Pages I don't have the ability to configure a server side redirect to feed_rss_created.xml.

Is there a way to configure the plugin to use my desired feed filename?
Alternatively, I'd love to hear other suggestions on how to resolve this without breaking existing links.

Thanks!

[Doubt] Does it conform to RSS 2.0 spec?

I find that in this w3schools reference that length is a required attribute. I tried parsing it with the ruby RSS parser and it fails validation with MissingAttributeError for length.

Interaction with mkdocs-material, images produces by Social plugin cause error

When using the social plugin in conjunction with the RSS plugin, I get a huge amount of these errors.

WARNING:root:Remote image could not been reached: http://127.0.0.1:8000/assets/images/social/blog/posts/14-results.png. Trying again with GET and disabling SSL verification. Attempt: 1. Trace: <urlopen error [Errno 61] Connection refused> WARNING:root:Remote image could not been reached: http://127.0.0.1:8000/assets/images/social/blog/posts/14-results.png. Trying again with GET and disabling SSL verification. Attempt: 2. Trace: <urlopen error [Errno 61] Connection refused>

The author of Material for MkDocs analyzed the following @squidfunk :

The RSS plugin fetches the image and that seems to run into an error with SSL. Please report this upstream.

Configuration mismatch between site_author and managingEditor

The MkDocs configuration for site_author is corresponding to the managingEditor element according to the plugin documentation. However, the site_author populates the HTML meta tag, <meta name="author" content="Author Name">, and expects a name while the <managingEditor>-element expects an e-mail adress. This results in an invalid XML-file according to the W3C valdiator which in turn seems to not be processesed by some RSS readers.

Steps to reproduce

1. Create a basic MkDocs-site using with the mkdocs-rss-plugin.
2. Add site_author in the MkDocs configuration using a name and not an e-mail.
3. Do not use any other page meta author information.
4. Validate generated XML file with the W3C validator.

Suggestion
Provide an override for managingEditor in the plugin configuration.

Please add author support in rss feed item

I saw the source code and figured out author support is not available. We want the blog authors name in the feed items.
Can you add that please?

RSS plugin is throwing error with mkdocs-material blog

When I run the link via a RSS Validator and I get an error for the author name:

line 1, column 433: Invalid email address: zeren [help]

... Hello again world!</title> <author>zeren</author> <category>Bar</categor ...

and also description error like this:

line 1, column 676: Missing channel element: description [help]
... n 2022 00:00:00 +0000</pubDate> </item> </channel></rss>

---

My mkdocs.yml file:

site_name: My Docs
theme:
  name: material

plugins:
  - blog:
      enabled: true
      blog_dir: blog/
  - rss:
      match_path: blog/posts/.*
      date_from_meta:
        as_creation: date
      categories:
        - categories
        - tags

nav:
  - Blog:
    - blog/index.md

Example the a post:

---
draft: false
date: 2022-01-31
categories:
    - General
tags:
  - Foo
  - Bar
authors:
  - "zeren"
---

# Hello again world!


Helloooo!

my .author.yml file in blog/

zeren:
  name: zeren
  description: Testing
  avatar: http://placekitten.com/300/300

Direct link to github pages test: https://zerenxyz.github.io/testing-mkdocs/blog/

fetch abstract up till well known `<!-- more -->` tag

👋
It is quite common for the markdown-based blog engines/themes to leverage the well known <!-- more --> tag to auto-generate the abstracts when the post is rendered.

It makes sense to expose an option for RSS plugin to fetch the post abstract up till that tag instead of a hard cut on the char limit.

Compress output XML

RSS plugin is not compatible with the categories of mkdocs-material blog

If I use the meta information "categories" in the mkdocs-material blog, the RSS plugin will generate an item for each category in the RSS XML. However, these items lack any other description information.

Example the a post:

---
date: 2024-04-09
categories:
    - General
authors:
  - "steven"
---

# Hello again world!


Hello world!

the feed_rss_created.xml:

<item>
  <title>General</title>
  <description><h1>General</h1></description>
  <pubDate>Tue, 09 Apr 2024 19:02:24 +0000</pubDate>
</item>
<item>
  <title>2024</title>
  <description><h1>2024</h1></description>
  <pubDate>Tue, 09 Apr 2024 19:02:24 +0000</pubDate>
</item>

Is there any way to remove the contents of category or archive items from the RSS feed? In my opinion, these empty items seem to serve no purpose. Thank you.

Need exclude options

I need exclude options to exclude some pages that generated by ohter plugins, like mkdocs-plugin-tags

Invalid date

The date being invalid, the XML generation is stopped.

Example : 2021-10-XX

Deprecation of Theme._vars

Hi all,

using the HEAD versions of mkdocs today, I stumbled across this:

mkdocs serve --watch-theme
INFO    -  Building documentation...
INFO    -  DeprecationWarning: Do not access Theme._vars, instead access the keys of Theme
           directly.
             File
           "/Users/avoss/src/mkdocs-material/devpt/venv/lib/python3.11/site-packages/mkdocs_rss_plugin/util.py",
           line 624, in guess_locale
               locale = mkdocs_config.get("theme")._vars.get("locale")
             File "/Users/avoss/src/mkdocs-material/devpt/mkdocs/mkdocs/theme.py", line
           81, in _vars
               warnings.warn(

This seems to have been introduced in MkDocs 1.5.0 (see bottom of the list of changes)? Not sure why I have not stumbled across this before...

Did a quick search and it seems there is one other place where this would need to be changed.

Hope this helps and that it is an obvious one-liner to fix.

Best wishes,

Alex

Dependabot couldn't authenticate with https://pypi.python.org/simple/

Dependabot couldn't authenticate with https://pypi.python.org/simple/.

You can provide authentication details in your Dependabot dashboard by clicking into the account menu (in the top right) and selecting 'Config variables'.

View the update logs.

Incompatibility with submodules (using mkdocs-monorepo-plugin)

Hello,

I started using mkdocs-rss-plugin but noticed that at the moment it's not compatible with mkdocs-monorepo-plugin. When I run mkdocs build I get the following output letting me know that the plugin couldn't find the dates for files in the submodules (in this case, the ones inside submodules/chart/):

$ mkdocs build
INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /home/paulo/docs/site 
WARNING -  Dates could not be retrieved for page: /home/paulo/docs/submodules/chart/docs/index.md.
WARNING -  Dates could not be retrieved for page: /home/paulo/docs/submodules/chart/docs/requirements.md.
WARNING -  Dates could not be retrieved for page: /home/paulo/docs/submodules/chart/docs/configuration/monitoring.md.
WARNING -  Dates could not be retrieved for page: /home/paulo/docs/submodules/chart/docs/configuration/integrations/bitbucket-cloud.md.
WARNING -  Dates could not be retrieved for page: /home/paulo/docs/submodules/chart/docs/configuration/integrations/bitbucket-server.md.
[...]

Since this plugin is based on the plugins by Tim Vink (which I'm also using), I checked how those plugins work and they determine the local Git repository for each file before using Git to obtain the metadata on the file, as seen here:

https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/blob/d4303ad2efd4d4cda49116d8e8bdb0aa5012d4d3/mkdocs_git_revision_date_localized_plugin/util.py#L91

Would you be willing to implement the same mechanism on mkdocs-rss-plugin to make it compatible with submodules?

Error when using "enabled: false" together with "match_path"

I get the following error if I try to disable the RSS feed generation using the new option enabled: false:

$ mkdocs build
INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /home/prcr/Codacy/git/docs/site 
ERROR   -  Error reading page 'index.md': 'GitRssPlugin' object has no attribute 'match_path_pattern' 
Traceback (most recent call last):
  File "/home/prcr/.local/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/usr/lib/python3/dist-packages/click/core.py", line 722, in __call__
    return self.main(*args, **kwargs)
  File "/usr/lib/python3/dist-packages/click/core.py", line 697, in main
    rv = self.invoke(ctx)
  File "/usr/lib/python3/dist-packages/click/core.py", line 1066, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/lib/python3/dist-packages/click/core.py", line 895, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/lib/python3/dist-packages/click/core.py", line 535, in invoke
    return callback(*args, **kwargs)
  File "/home/prcr/.local/lib/python3.7/site-packages/mkdocs/__main__.py", line 152, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "/home/prcr/.local/lib/python3.7/site-packages/mkdocs/commands/build.py", line 271, in build
    _populate_page(file.page, config, files, dirty)
  File "/home/prcr/.local/lib/python3.7/site-packages/mkdocs/commands/build.py", line 175, in _populate_page
    'page_content', page.content, page=page, config=config, files=files
  File "/home/prcr/.local/lib/python3.7/site-packages/mkdocs/plugins.py", line 94, in run_event
    result = method(item, **kwargs)
  File "/home/prcr/.local/lib/python3.7/site-packages/mkdocs_rss_plugin/plugin.py", line 183, in on_page_content
    if not self.match_path_pattern.match(page.file.src_path):
AttributeError: 'GitRssPlugin' object has no attribute 'match_path_pattern'

This happens because when we have enabled: false, the plugin completely skips the initialization of the config object:

https://github.com/Guts/mkdocs-rss-plugin/blob/main/mkdocs_rss_plugin/plugin.py#L87-L88

However, during the event on_page_content, the plugin tries to read the uninitialized self.match_path_pattern:

https://github.com/Guts/mkdocs-rss-plugin/blob/main/mkdocs_rss_plugin/plugin.py#L182-L184

I believe that all logic in this event should also be skipped instead when enabled: false. 🤔

Use absolute url for images in feeds?

First, stunning plugin, thanks so much for supporting the indie web!

I've added mkdocs-rss-plugin to my blog and it worked (almost) flawlessly.
https://du.nkel.dev/

The images shown in the description do not contain the full URL:
https://du.nkel.dev/feed_rss_created.xml

e.g.:

<img alt="hifi" src="img/hifi.jpg">

.. which is why they are not shown in preview.

Would it be possible to add this full url somwhere in the settings?

date detection from "git log" is broken when git client is configured with "--show-signature"

I can't build mkdocs sites from repositories where commits are signed and git client is configured to always show commit signature.

The problem seems to be here:

mkdocs-rss-plugin/mkdocs_rss_plugin/util.py

Lines 145 to 159 in c9b1c8b

	if not dt_created:
	dt_created = self.repo.log(
	in_page.file.abs_src_path,
	n=1,
	date="short",
	format="%at",
	diff_filter="AR",
	)
	if not dt_updated:
	dt_updated = self.repo.log(
	in_page.file.abs_src_path,
	n=1,
	date="short",
	format="%at",
	)

It assumes that git log -1 --date=short --format="%at"'s output will only contain the timestamp and nothing else, which isn't true.

My gitconfig contains:

[log]
    showSignature = true

Which is equivalent to git log --show-signature ..., and the output will always contain commit signature info:

$ git log --date=short -1 --format="%at"
gpg: Signature made Tue Jun 21 17:19:48 2022 PDT
gpg:                using EDDSA key 90DA57F75A16D8729DBEE227CD67D78AC53D68C5
gpg: Good signature from "Yuhao Zhang <[email protected]>" [ultimate]
1655857188

And the plugin will crash at:

mkdocs-rss-plugin/mkdocs_rss_plugin/util.py

Lines 179 to 180 in c9b1c8b

	int(dt_created),
	int(dt_updated),

Because the whole string cannot be converted to int.

Question: Per item image in `page.meta.image` with relative path

Hey,

I have included this plugin today into my site (thank you for that, pretty happy with it 🤗 ).

I populated the page.meta.image in all my sites with a relative path. Would it be possible to not only prepend the site_url, but also fill in the relative path?
Otherwise I'd have to use absolute links, which I wanted not to in case I'd have to rename something 🤔

Please remove dependency pinning, at least for MkDocs

The recent sentiment in Python world is that upper range dependency restrictions are harmful in libraries.

As for MkDocs itself, I routinely test that I don't break plugins with new releases, via https://github.com/mkdocs/regressions, so it's even more unnecessary.

Please remove these upper range restrictions:

mkdocs-rss-plugin/setup.py

Lines 54 to 55 in 910de75

	"GitPython>=3.1,<3.2",
	"mkdocs>=1.1,<1.4",

All this does is cause unnecessary issues:

• squidfunk/mkdocs-material#4438 (comment)
• ojacques/mkdocs-git-committers-plugin-2#21 (comment)

---

• Meanwhile, a new release is needed in any case, with #135

Links incorrect in feed

Hi there,

I have an RSS feed on my blog here: https://tempered.works/feed_rss_created.xml

The links in the most recent post for images and other internal content are wrong - appears to be literally what's in the markdown, not the rendered version

src="./assets/hero.webp"></p><p>When I wrote about <a href="../2024-03-23-irresponsible-expertise-install-python-package/index.md">dangerous advice

Image should be: https://tempered.works/2024-03-31-exploring-setup-py/assets/hero.webp
Link should be: https://tempered.works/posts/2024/03/23/irresponsible-expertise---python-packages/

I think there's a couple of folks raised similar issues with cover images before, but I'm also seeing the issue on other internal links.

Repo https://github.com/brabster/tw-site-mkdocs

Initially raised with mkdocs-material and suggested I raise here

Semantic versioning support

Hi, first of all thanks for the plugin, I've had this need for a long time.

Even though the current functionality works flawlessly, I think we can use the semantic
versioning functionality to make the RSS feed even richer.

The idea is to create commits following a specific format that describes what kind of change you're making. I've been following this practice for a while with the following personal commit convention:

{type_of_change}({file_changed}): {short_description}
{full_description}

Where:

• type_of_change is one of:

  • feat: Add new content to the repository, it can be a new file or new content on an
    existent file.
  • fix: Correct existing content.
  • style: Correct grammar, orthography or broken links.
  • ci: Change the continuous integration pipelines.
  • chore: Update the python dependencies required to build the site.

• file_changed: name of the file changed (without the .md extension)

For example: a single feat
commit or
a multientry commit

With this information in the git log we could generate RSS feed entries whose:

• Title is taken from short_description.
• Body is taken from full_description.
• The link to the article can be built from file_changed.
• Only feat and fix entries are evaluated (no one wants to receive an rss
  notification of a typo fix in an article).
• An entry will be created for each change, so multientry commits will have many entries.

We could also support a "newsletter" mode inspired by
python-semantic-release
and
commitizen bump, where each time you
make a release in your documentation, all the changes in your repo since the last git
tag are processed into a single entry where the changes are grouped by file_changed.

I know the proposal will add complexity to the plugin, and I understand why you wouldn't
want that, but if you are interested, I'd like to help building it.

Date ambiguity for sites built with GitHub Action

Description

I have a mkdocs site hosted in GitHub, and the deployment relies on GitHub Action, every time there is an update on the main, the update will be pushed to the site.

The issue about the feed_rss_updated.xml is in fact every post got updated so the updated time of each post is identical, leading to the results to be identical however the update is.

Sample RSS

This is an example of the RSS feed, in fact it is static because of the cause I mentioned above. https://bullettech.github.io/BulletTech/feed_rss_updated.xml

Question

Can the git log change date be used to retrieve the list of posts that get updated lately? If using the deployed date, then the returned list always remain static seemingly.

Can't make plugin work with mkdocs-material Docker image

Hi, we from https://emacs-lsp.githb.io/lsp-mode intend to use your plugin emacs-lsp/lsp-mode#2184.
We usemkdocs-material which already works for us for months but when we add your plugin It seems to happen some error:

Error

Docker image:

FROM squidfunk/mkdocs-material
RUN pip install --no-cache-dir \
        'mkdocs-awesome-pages-plugin>=2.2.1' \
        'mkdocs-git-revision-date-localized-plugin>=0.4' \
        'mkdocs-minify-plugin>=0.3' \
        'mkdocs-redirects>=1.0' \
        'mkdocs-rss-plugin>=0.6.1';

v1.13.1 breaks mkdocs serve (v1.12.2 works)

When I run serve the build, I see this error:

mkdocs serve
...
DEBUG   -  Running 3 `page_content` events
DEBUG   -  meta-descriptions: Adding meta description from front matter: host/self.md
DEBUG   -  Reading: news/2024-04-10-website.md
DEBUG   -  Running 5 `page_markdown` events
DEBUG   -  Running 5 `page_markdown` events
DEBUG   -  Running 3 `page_content` events
DEBUG   -  meta-descriptions: Adding meta description from first paragraph:
           /home/nicco/open-web-calendar/.tox/docs/tmp/mkdocs_mdpo_q7uxxce3/en/news/2024-04-10-website/index.md
DEBUG   -  Running 5 `page_markdown` events
DEBUG   -  Running 3 `page_content` events
DEBUG   -  meta-descriptions: Adding meta description from first paragraph:
           /home/nicco/open-web-calendar/.tox/docs/tmp/mkdocs_mdpo_q7uxxce3/de/news/2024-04-10-website/index.md
DEBUG   -  Running 5 `page_markdown` events
DEBUG   -  Running 3 `page_content` events
DEBUG   -  meta-descriptions: Adding meta description from first paragraph:
           /home/nicco/open-web-calendar/.tox/docs/tmp/mkdocs_mdpo_q7uxxce3/es/news/2024-04-10-website/index.md
DEBUG   -  Running 5 `page_markdown` events
DEBUG   -  Running 3 `page_content` events
DEBUG   -  meta-descriptions: Adding meta description from first paragraph:
           /home/nicco/open-web-calendar/.tox/docs/tmp/mkdocs_mdpo_q7uxxce3/nb_NO/news/2024-04-10-website/index.md
DEBUG   -  Running 5 `page_markdown` events
DEBUG   -  Running 3 `page_content` events
DEBUG   -  meta-descriptions: Adding meta description from first paragraph:
           /home/nicco/open-web-calendar/.tox/docs/tmp/mkdocs_mdpo_q7uxxce3/it/news/2024-04-10-website/index.md
DEBUG   -  Running 5 `page_markdown` events
DEBUG   -  Running 3 `page_content` events
DEBUG   -  meta-descriptions: Adding meta description from first paragraph:
           /home/nicco/open-web-calendar/.tox/docs/tmp/mkdocs_mdpo_q7uxxce3/th/news/2024-04-10-website/index.md
DEBUG   -  Running 3 `page_content` events
DEBUG   -  meta-descriptions: Adding meta description from first paragraph: news/2024-04-10-website.md
DEBUG   -  [RSS-plugin]: Extracting dates for news/2024-04-10-website.md
DEBUG   -  [RSS-plugin]: Not found: /home/nicco/open-web-calendar/.cache/plugin/social/5cf12f946dfbb3df6df3c1a5d9bfc9d8.png
DEBUG   -  [RSS-plugin]: Not found:
           /home/nicco/open-web-calendar/.tox/docs/tmp/mkdocs_gjiuwg1m/home/nicco/open-web-calendar/assets/images/social/news/2024-04-10-website.png
DEBUG   -  [RSS-plugin]: Social card still not exists locally. Trying to retrieve length from remote image:
           http://127.0.0.1:8000/assets/images/social/news/2024-04-10-website.png. Note that would work only if the social card image has been
           already published before the build.
ERROR   -  Error reading page 'news/2024-04-10-website.md': HTTPConnectionPool(host='127.0.0.1', port=8000): Max retries exceeded with url:
           /assets/images/social/news/2024-04-10-website.png (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at
           0x7a57c360bed0>: Failed to establish a new connection: [Errno 111] Connection refused'))
DEBUG   -  Running 1 `build_error` events

ConnectionError: HTTPConnectionPool(host='127.0.0.1', port=8000): Max retries exceeded with url: /assets/images/social/news/2024-04-10-website.png (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7a57c360bed0>: Failed to establish a new connection: [Errno 111] Connection refused'))
docs: exit 1 (3.74 seconds) /home/nicco/open-web-calendar> mkdocs -v serve pid=1274320
  docs: FAIL code 1 (43.62=setup[39.88]+cmd[3.74] seconds)
  evaluation failed :( (43.69 seconds)

The build with version 1.12.2 works fine.

Repo: https://github.com/niccokunzmann/open-web-calendar/

mkdocs build works.

See also:

• niccokunzmann/open-web-calendar#412

multiple instances? #feature_request

Hi,

I am working on a template for creating blogs using Material for MkDocs and as part of this would like to use the fact that the blog plugin can be instantiated multiple times. This is both to show off the fact that it can and to be able to show different blog configurations.

Now, in the template, I am integrating the RSS plugin as well. Correct me if I am wrong but it does not support multiple instances itself, right? So, for the moment, only one of the blogs on the site will be included in the RSS.

It would seem sensible to me to add multi-instance support and I am willing to create a PR for this, though I realize that it might be a more complex one. I am also not entirely sure just how big a commitment this will turn out to be and when I might have enough clear road ahead to take it on but let's hope it is measured in weeks, not months.

Cheers, Alex

Question regarding pubDate

I have a question regarding the <pubDate> property of the different items created by this plugin.

As of right now do I override it by using the date metadata which results in dates such as Fri, 21 Jul 2023 00:00:00 +0200 when I set date: 2023-07-21

The thing is, that I want to use this RSS feed together with Mastofeed to automatically publish posts on my Mastodon account whenever I create a new blog post.
What makes this a problem is the fact that, the <pubDate> and/or <lastBuildDate are never older than the <pubDate> of my latest post, since these dates also include a time (And also have a -0000 time shift), so my posts are always considered as "old" and not published on Mastodon.

I was now considering to just remove the Metadata from the RSS plugin options, so that it would default to... something.
When I understand it correctly, should this mean that it would pull the date of when the page has been created from Git Metadata for the create feed?

If so, do I need to look out for some common pitfalls (i.e. specific date patterns to set in the plugin settings), or should it work fine?

I'm just a bit worried, that the Mastodfeed site could go crazy, because I use a CI pipeline for automatic publishing and that one has shallow git fetching (--fetch-depth=1), so dates are messed up.
Tho, I did fix this now using git fetch --unshallow, but I still fear there might be issues?
If you can, I would appreciate if you take a look at this file to see if that should create proper feed_rss_created.xml files with the right creation (<pubDate>) dates...
https://codeberg.org/Andre601/blog-source/src/branch/master/.woodpecker.yml

The plugin does not work without git

Use case

I'm building a website with mkdocs-material+mkdocs_plugin_rss with gitlab CI.
I use python:3.10-alpine image on that CI, which does not seem to include git.

My mkdocs.yml section about rss is:

...
plugins:
  - rss:
      use_git: false
      match_path: blog/posts/.* 
      date_from_meta:
        as_creation: date
      categories:
        - categories

Traceback (most recent call last):
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/git/__init__.py", line 296, in <module>
    refresh()
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/git/__init__.py", line 287, in refresh
    if not Git.refresh(path=path):
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/git/cmd.py", line 631, in refresh
    raise ImportError(err)
ImportError: Bad git executable.
The git executable must be specified in one of the following ways:
    - be included in your $PATH
    - be set via $GIT_PYTHON_GIT_EXECUTABLE
    - explicitly set via git.refresh(<full-path-to-git-executable>)
All git commands will error until this is rectified.
This initial message can be silenced or aggravated in the future by setting the
$GIT_PYTHON_REFRESH environment variable. Use one of the following values:
    - quiet|q|silence|s|silent|none|n|0: for no message or exception
    - warn|w|warning|log|l|1: for a warning message (logging level CRITICAL, displayed by default)
    - error|e|exception|raise|r|2: for a raised exception
Example:
    export GIT_PYTHON_REFRESH=quiet
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
  File "/builds/testcy/cyber/.venv/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/mkdocs/__main__.py", line 281, in build_command
    cfg = config.load_config(**kwargs)
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/mkdocs/config/base.py", line 374, in load_config
    errors, warnings = cfg.validate()
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/mkdocs/config/base.py", line 231, in validate
    run_failed, run_warnings = self._validate()
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/mkdocs/config/base.py", line 188, in _validate
    self[key] = config_option.validate(value)
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/mkdocs/config/config_options.py", line 186, in validate
    return self.run_validation(value)
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/mkdocs/config/config_options.py", line 1075, in run_validation
    self.load_plugin_with_namespace(name, cfg)
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/mkdocs/config/config_options.py", line 1113, in load_plugin_with_namespace
    return (name, self.load_plugin(name, config))
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/mkdocs/config/config_options.py", line 1131, in load_plugin
    plugin_cls = self.installed_plugins[name].load()
  File "/usr/local/lib/python3.10/importlib/metadata/__init__.py", line 171, in load
    module = import_module(match.group('module'))
  File "/usr/local/lib/python3.10/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1006, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 688, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 883, in exec_module
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/mkdocs_rss_plugin/plugin.py", line 37, in <module>
    from mkdocs_rss_plugin.util import Util
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/mkdocs_rss_plugin/util.py", line 24, in <module>
    from git import (
  File "/builds/testcy/cyber/.venv/lib/python3.10/site-packages/git/__init__.py", line 298, in <module>
    raise ImportError("Failed to initialize: {0}".format(_exc)) from _exc
ImportError: Failed to initialize: Bad git executable.
The git executable must be specified in one of the following ways:
    - be included in your $PATH
    - be set via $GIT_PYTHON_GIT_EXECUTABLE
    - explicitly set via git.refresh(<full-path-to-git-executable>)
All git commands will error until this is rectified.
This initial message can be silenced or aggravated in the future by setting the
$GIT_PYTHON_REFRESH environment variable. Use one of the following values:
    - quiet|q|silence|s|silent|none|n|0: for no message or exception
    - warn|w|warning|log|l|1: for a warning message (logging level CRITICAL, displayed by default)
    - error|e|exception|raise|r|2: for a raised exception
Example:
    export GIT_PYTHON_REFRESH=quiet
Cleaning up project directory and file based variables 00:00
ERROR: Job failed: command terminated with exit code 1

I don't know if you can import git if and only if the use_git option is enabled, but right now that plugin don't work without the git executable.

However, thank you for this plugin and all the work that you've done on it !

License change: GPL3 --> MIT. Committers agreement required.

It has been reported to me that the license I chose at the beginning of the development (GNU GPL v3) could cause problems for some projects or contributors.

I therefore propose to change to a more permissive license aligned with other projects in the Mkdocs ecosystem: MIT.

For this, I need each committer to agree:

• @liang2kl
• @prcr
• @rmorshea
• @mondeja
• @dcode
• @timvink (not direct committer, but author of first git management)

Please, could you comment below to agree or disagree to this change?

Support for custom pages in rss

Is it possible to add a option to specify which folders I want to add to rss XML?

plugins:
  - rss:
    path: ["/tutorials", "/blog"]

Thanks!

Feature request: allow running without git, i.e. with only info from page.meta (YAML frontmatter)

08:45:50.953 | Successfully installed babel-2.11.0 beautifulsoup4-4.11.1 cssselect-1.2.0 lxml-4.9.1 markdown2-2.4.6 mkdocs-material-8.5.10+insiders.4.26.3 paginate-0.5.6 pyquery-1.4.3 readtime-2.0.0 regex-2022.10.31 soupsieve-2.3.2.post1
-- | --
08:45:50.981 | WARNING: You are using pip version 20.2b1; however, version 22.3.1 is available.
08:45:50.981 | You should consider upgrading via the '/opt/buildhome/python3.7/bin/python3.7 -m pip install --upgrade pip' command.
08:45:53.903 | Traceback (most recent call last):
08:45:53.904 | File "/opt/buildhome/python3.7/bin/mkdocs", line 8, in <module>
08:45:53.904 | sys.exit(cli())
08:45:53.904 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/click/core.py", line 1130, in __call__
08:45:53.905 | return self.main(*args, **kwargs)
08:45:53.905 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/click/core.py", line 1055, in main
08:45:53.905 | rv = self.invoke(ctx)
08:45:53.905 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/click/core.py", line 1657, in invoke
08:45:53.905 | return _process_result(sub_ctx.command.invoke(sub_ctx))
08:45:53.905 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/click/core.py", line 1404, in invoke
08:45:53.905 | return ctx.invoke(self.callback, **ctx.params)
08:45:53.905 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/click/core.py", line 760, in invoke
08:45:53.906 | return __callback(*args, **kwargs)
08:45:53.906 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/__main__.py", line 247, in build_command
08:45:53.906 | cfg = config.load_config(**kwargs)
08:45:53.906 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/config/base.py", line 363, in load_config
08:45:53.906 | errors, warnings = cfg.validate()
08:45:53.906 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/config/base.py", line 228, in validate
08:45:53.906 | run_failed, run_warnings = self._validate()
08:45:53.906 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/config/base.py", line 186, in _validate
08:45:53.906 | self[key] = config_option.validate(value)
08:45:53.907 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/config/config_options.py", line 147, in validate
08:45:53.907 | return self.run_validation(value)
08:45:53.907 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/config/config_options.py", line 939, in run_validation
08:45:53.907 | self.load_plugin_with_namespace(name, cfg)
08:45:53.907 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/config/config_options.py", line 975, in load_plugin_with_namespace
08:45:53.907 | return (name, self.load_plugin(name, config))
08:45:53.907 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/config/config_options.py", line 1001, in load_plugin
08:45:53.907 | plugin = plugin_cls()
08:45:53.907 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs_rss_plugin/plugin.py", line 65, in __init__
08:45:53.908 | self.util = Util()
08:45:53.908 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs_rss_plugin/util.py", line 74, in __init__
08:45:53.908 | CiHandler(git_repo.git).raise_ci_warnings()
08:45:53.908 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs_rss_plugin/git_manager/ci.py", line 28, in raise_ci_warnings
08:45:53.908 | n_commits = self.commit_count()
08:45:53.908 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs_rss_plugin/git_manager/ci.py", line 87, in commit_count
08:45:53.908 | refs = [x.split()[0] for x in refs]
08:45:53.908 | File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs_rss_plugin/git_manager/ci.py", line 87, in <listcomp>
08:45:53.909 | refs = [x.split()[0] for x in refs]
08:45:53.909 | IndexError: list index out of range

Naming of RSS feed and autodetection by clients

I am using the miniflux RSS reader client.

When adding a feed it just asks for the base url - I give my mkdocs blog with this mkdocs-rss-plugin enabled.
It returns with an error message Unable to find any subscription..

If I supply the feed_rss_created.xml or feed_rss_updated.xml urls it works.

Is this a problem with miniflux or with mkdocs?

When page.meta.description does not exist, convert markdown into html

Multiple authors / RSS email

Hello again,

When there are multiple authors, the RSS email will concatenate both strings in the from field.

E.G.

author:
- Mary Jane
- Peter Parker

Email = From: Mary JanePeter Parker

I tried to cheat and put a space at the end of the names in the yaml file, but it sanitizes it. Is there a good way of getting a space between each author if multiple?

Support defining a mapping between author identifier and the author in the feed

The RSS standard specifies the author should be [email protected] (John Doe). In the documents I'd like to use a username, for example the github username, as author. Would it be possible to implement a mapping between usernames and RSS authors?
I'm thinking aboud a new config setting and a yaml file that maps the authors to RSS Name + Email definitions.
Alternatively one could implement rss_author and rss_authors metadata.

Background information:
I'm using the mkdocs-material theme with the blog plugin. The blog plugin can also render pages for authors. With the current setup, specifying a RSS conform author, the URL to the authors page looks quite ugly (containing %40 for the @ and several spaces).

Do you thinkt that's a good idea? Then I'd start with an implememtation and open a pull request.

Use git contributors from git log to populate feed items authors

From #34

Thanks for your inputs.

We can add the feature through page.meta.author.

I think we should take into an account that a page can have multiple authors, like co-contributors in git.

git contributor is also a good feature but page.meta.author should override git contributor.

The plugin was first thought to use git information. Nevertheless, we can move forward more easily with the metadata of the page. Let's start by this side, then I'll see the git logic from @timvink plugins.

The formatting should be like this

 <author>
 <name>Krishan Subudhi</name>
  </author>

Refering to the RSS standard to ensure our compliance. the author tag should have an email address:

• https://www.w3schools.com/XML/rss_tag_author.asp
• https://validator.w3.org/feed/docs/rss2.html#hrelementsOfLtitemgt

It'll be natural with the git log, but for the page.meta it's on the page writer.

Originally posted by @Guts in #34 (comment)

match_path issues

Hello,

My blog doesn't use the default 'blog' value. I have the folder named 'my-news'

docs/
   my-news/
      posts/

in my mkdocs.yml

 - blog:
      blog_dir: my-news
  - rss:
      abstract_chars_count: 150
      match_path: my-news/posts/.*
      date_from_meta:
        as_creation: date
      categories:
        - categories
        - tags

I only get matches if i do
match_path: my-news

But that matches the Archive and Category folders and I get double posts.

I'm not exactly sure where I'm going wrong here

Add ability to include/exclude files using regex pattern

An issue to track some discussion from #43 (comment).

Language code might differ from RSS Spec

Example

• Mkdocs: en_US. (underscore)
• RSS Spec: en-US. (hyphen)

Note: RSS also accepted lowercase en-us.

Explaination

• theme.locale of Mkdocs basically uses ISO-639-1 2-letter abbreviation (en), and may also include a territory suffix (_US).
• And the language code in RSS follows W3C / RFC 1766 / full ISO-639. I guess it's consistent with HTML, which follows RFC 5646 (a newer version of RFC 1766).

Additionally, you can't write hyphen (en-US) in mkdocs.yml.

$ mkdocs build
ERROR    -  Config value 'theme': Invalid value for locale: expected only letters, got 'en-US'
Aborted with 1 Configuration Errors!

Possible fix

(I can turn it into a PR if you want)

Change the following line in .util.Util.guess_locale

mkdocs-rss-plugin/mkdocs_rss_plugin/util.py

Line 563 in 769744e

return mkdocs_config.get("theme")._vars.get("locale")

to

locale = mkdocs_config.get("theme")._vars.get("locale")
return f"{locale.language}-{locale.territory}"

TypeError: strptime() argument 1 must be str, not datetime.datetime

It seems 1.13.0 introduces a few new bugs

My pipeline worked fine, but is complaining now.

https://github.com/DLS5-Omics/multimolecule/actions/runs/9465496343/job/26075394011

created date and updated date in metadata

Hello,

I have both dates under the date key in the yaml metadata, could you please provide the syntax to show the created date ?

becase with current syntax:

date_from_meta:
    as_creation: date

I got error:
[rss-plugin] Creation date of xxx.md has not been recognized.

https://squidfunk.github.io/mkdocs-material/plugins/blog/?h=created#meta.date

New feature: easily customisable jinja2 templates per-feed?

I'm just now getting my site and feed setup, and it seems like there are an infinite number RSS feed configuration options in the world. (Custom icons, metadata, etc.) I would like to be able to have more control of the generated feed from this plugin, and it seems like the easiest way to do this would be similar to how Material for MkDocs handles it, with the ability to add a jinja2 template to a project, based on templates/rss.xml.jinja2 as a starting point.

I would envision this could be enabled with an additional config option, such as rss_feed_template:, since I would want to be able to use different templates when multiple feeds are used.

I would be happy to write this feature. It's something I need to do for myself anyway, and it would be easy to make it universal. But I wanted to see if this was a feature that would be valuable here, and, if you have any thoughts or suggestions on what I consider before I create it.

Thanks!
Brian

'NoneType' object is not iterable when using 0.19.0

Hello,

When trying to build a site that I maintain using mkdocs-rss-plugin 0.19.0 I get the following:

Run mkdocs build
  mkdocs build
  shell: /usr/bin/bash -e {0}
  env:
    pythonLocation: /opt/hostedtoolcache/Python/3.9.7/x64
    LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.9.7/x64/lib
INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /home/runner/work/docs/docs/site 
ERROR   -  Error reading page 'release-notes/cloud/cloud-2021-08.md': 'NoneType' object is not iterable 
Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.9.7/x64/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/opt/hostedtoolcache/Python/3.9.7/x64/lib/python3.9/site-packages/click/core.py", line 1137, in __call__
    return self.main(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.9.7/x64/lib/python3.9/site-packages/click/core.py", line 1062, in main
    rv = self.invoke(ctx)
  File "/opt/hostedtoolcache/Python/3.9.7/x64/lib/python3.9/site-packages/click/core.py", line 1668, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/opt/hostedtoolcache/Python/3.9.7/x64/lib/python3.9/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/opt/hostedtoolcache/Python/3.9.7/x64/lib/python3.9/site-packages/click/core.py", line 763, in invoke
    return __callback(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.9.7/x64/lib/python3.9/site-packages/mkdocs/__main__.py", line 152, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "/opt/hostedtoolcache/Python/3.9.7/x64/lib/python3.9/site-packages/mkdocs/commands/build.py", line 271, in build
    _populate_page(file.page, config, files, dirty)
  File "/opt/hostedtoolcache/Python/3.9.7/x64/lib/python3.9/site-packages/mkdocs/commands/build.py", line 174, in _populate_page
    page.content = config['plugins'].run_event(
  File "/opt/hostedtoolcache/Python/3.9.7/x64/lib/python3.9/site-packages/mkdocs/plugins.py", line 94, in run_event
    result = method(item, **kwargs)
  File "/opt/hostedtoolcache/Python/3.9.7/x64/lib/python3.9/site-packages/mkdocs_rss_plugin/plugin.py", line 214, in on_page_content
    categories=self.util.get_categories_from_meta(
  File "/opt/hostedtoolcache/Python/3.9.7/x64/lib/python3.9/site-packages/mkdocs_rss_plugin/util.py", line 244, in get_categories_from_meta
    for category_label in categories_labels:
TypeError: 'NoneType' object is not iterable
Error: Process completed with exit code 1.

It's possible that this issue has to do with the existing metadata for the page where the process stopped.

do not generate rss feed for draft posts

Hi,
would it be possible to add a setting for not generating RSS feeds for markdown files that have

draft: true

in their frontmatter?

Add JSON Feed support

JSON has become the developers’ choice for APIs, and that developers will often go out of their way to avoid XML. RSS is nice as it has widespread support, but JSON is easier to use in ad-hoc applications, especially on frontend (point in case: I'm trying to add a small widget with latest articles from my blog right now).

Here's specification and mapping from RSS. Would you be interested in a PR implementing this?

Date shifted by timezone when using `date_from_meta`

First of all, great plugin! Material for MkDocs will get blog support tomorrow, and I'm finishing up the last small little details to make it awesome. Your plugin will be advertised on the documentation for adding RSS support, as it's the best one out there.

I've encountered a problem where the dates of blog articles are not correctly computed when date_from_meta is used. my configuration in mkdocs.yml is as follows:

plugins:
  - rss:
      match_path: blog/posts/.*
      date_from_meta:
        as_creation: date
      categories:
        - categories
        - tags

When I set a date in a blog article, the computed time is shifted by the UTC offset of the current timezone. For example:

---
date: 2022-05-05
---

Becomes:

<pubDate>Wed, 04 May 2022 22:00:00 -0000</pubDate>

IMHO, dates should be treated as UTC. I'm currently in UTC+2, so this seems to be the problem.

How to handle ampersands in titles?

My RSS feed is invalid because there are ampersands in titles.

Afaik there is no conversion done in mkdocs of special characters, where should this be handled? Should mkdocs-rss-plugin perhaps convert them?

Mangled descriptions without pretty-printing

I've noticed that when \n is removed (when pretty-printing is turned off), it causes descriptions that have newline separating
words to disappear, resulting in something like this: thiswas meant to be separated instead of this was meant to be separated

For now, the fix is to enable pretty-printing, but going forward it would probably be best to have something that won't mangle the text.

Min Python version to 3.10 is a problem for Netlify users

Hi there,

I use Netlify to run my site and unfortunately they currently only support Python 3.8 https://docs.netlify.com/configure-builds/available-software-at-build-time/. I see a move to 3.10 min in my branch that I just synced with main and boom

I'm not sure if updating past 3.8 is an option on Netlify, can't see a way. Had to pin back to an earlier commit to get back up and running. Might cause some problems if there's a lot of folks using it