Feature: add per-feed custom titles and abstracts

[toomanybrians]

This pull request allows an RSS feed to override the MkDocs default site_name: and/or site_description: settings to allow feed-specific titles and descriptions. This is useful when multiple instances of the plugin are used (for example, one for blog posts and another for doc updates), as it will allow RSS feed subscribers to know which feed is which.

It's also useful even with a single instance of the plugin, since sometimes the site title or description is SEO-optimized, while the RSS feed might want shorter or alternate versions.

To use this capability, add a feed_title: and/or feed_description: setting to the RSS feed plugin settings. If either of these keys is not included, the previous behavior of using the site-wide versions is used. This feature does not change any behavior of any existing configs.

A minimal example:

site_name: My awesome website
site_description: Obviously the best website that exists, because MkDocs is awesome!

plugins:
  - search
  - rss:
      match_path: blog/posts/.*      
      feed_title: My awesome blog feed
      feed_description: The best blog from the best site
  - rss:
      match_path: guide/.*      
      feed_title: Doc updates from the best site
      feed_description: Provides updates to documentation on this great site

I have updated the documentation, and also added tests.

(Comment updated to reflect latest changes to the PR)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 80.55%. Comparing base (7aa5e99) to head (1c17192).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #295      +/-   ##
==========================================
+ Coverage   80.49%   80.55%   +0.06%     
==========================================
  Files           9        9              
  Lines         610      612       +2     
  Branches      127      127              
==========================================
+ Hits          491      493       +2     
  Misses         82       82              
  Partials       37       37              

Flag	Coverage Δ
unittests	80.55% <100.00%> (+0.06%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
mkdocs_rss_plugin/config.py	100.00% <100.00%> (ø)
...lugin/integrations/theme_material_social_plugin.py	76.42% <ø> (ø)
mkdocs_rss_plugin/plugin.py	90.69% <ø> (ø)
mkdocs_rss_plugin/util.py	73.12% <ø> (ø)

[Guts]

Hi @toomanybrians

Thanks for your interest and your great contribution, especially since it does fit every contribution guideline. It's really appreciated.

2 suggestions:

• prefix new option with feed_: feed_description, feed_title
• use None as default value

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud

[toomanybrians]

Awesome, thanks for these suggestions! I have incorporated everything you suggested, confirmed all tests pass, and updated the PR. Thanks!

[Guts]

Thanks for taking every review in account. I merge right now and will release a new version next week because I want to wait a bit for having feedback about the latest release (yesterday).

[Guts]

Release as part of 1.13.2

Thanks again @toomanybrians!

[Guts]

I've made a bit of communication here https://mapstodon.space/@geojulien/112672843319595679. If you have a Mastodon account, I would like to credit your work.