allow per-feed customisations of title and description

Adds new `title:` and `description` options to the plugin which will be used in the generated feeds. If these keys are not present, the default MkDocs site-wide `site_title:` and `site_description:` will be used.

Author: toomanybrians

docs/configuration.md

@@ -367,6 +367,24 @@ At the end, into the RSS you will get:
 
 ----
 
+### :material-subtitles: `description`: override site description { #description }
+
+This option allows you to override the default MkDocs site description for the description tag in this RSS feed.
+This is useful if you have multiple instances of this plugin for multiple feeds. (For example, one feed
+for the blog, and a second for documentation updates.)
+
+This setting is optional. If you do not include it, the default site description will be used.
+
+```yaml
+plugins:
+  - rss:
+      description: The best blog from the best site
+```
+
+Default: Use the default MkDocs `site_description:`.
+
+----
+
 ### :material-alphabet-latin: `feeds_filenames`: customize the output feed URL { #feeds_filenames }
 
 > Since version 1.13.0.
@@ -478,6 +496,24 @@ Default: `False`.
 
 ----
 
+### :material-format-title: `title`: override site title { #title }
+
+This option allows you to override the default MkDocs site title for the title tag in this RSS feed.
+This is useful if you have multiple instances of this plugin for multiple feeds. (For example, one feed
+for the blog, and a second for documentation updates.)
+
+This setting is optional. If you do not include it, the default site title will be used.
+
+```yaml
+plugins:
+  - rss:
+      title: My awesome blog feed
+```
+
+Default: Use the default MkDocs `site_title:`.
+
+----
+
 ### :material-track-light: `url_parameters`: additional URL parameters { #url_parameters }
 
 This option allows you to add parameters to the URLs of the RSS feed items. It works as a dictionary of keys/values that is passed to [Python *urllib.parse.urlencode*](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlencode).

mkdocs_rss_plugin/config.py

@@ -44,6 +44,7 @@ class RssPluginConfig(Config):
     )
     comments_path = config_options.Optional(config_options.Type(str))
     date_from_meta = config_options.SubConfig(_DateFromMeta)
+    description = config_options.Type(str, default="")
     enabled = config_options.Type(bool, default=True)
     feed_ttl = config_options.Type(int, default=1440)
     feeds_filenames = config_options.SubConfig(_FeedsFilenamesConfig)
@@ -53,6 +54,7 @@ class RssPluginConfig(Config):
     match_path = config_options.Type(str, default=".*")
     pretty_print = config_options.Type(bool, default=False)
     rss_feed_enabled = config_options.Type(bool, default=True)
+    title = config_options.Type(str, default="")
     url_parameters = config_options.Optional(config_options.Type(dict))
     use_git = config_options.Type(bool, default=True)
     use_material_social_cards = config_options.Type(bool, default=True)

mkdocs_rss_plugin/plugin.py

@@ -115,14 +115,16 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig:
             "author": config.site_author or None,
             "buildDate": formatdate(get_build_timestamp()),
             "copyright": config.copyright,
-            "description": config.site_description,
+            "description": self.config['description'] if self.config['description'] \
+                else config['site_description'],
             "entries": [],
             "generator": f"{__title__} - v{__version__}",
             "html_url": self.util.get_site_url(mkdocs_config=config),
             "language": self.util.guess_locale(mkdocs_config=config),
             "pubDate": formatdate(get_build_timestamp()),
             "repo_url": config.repo_url,
-            "title": config.site_name,
+            "title": self.config['title'] if self.config['title'] \
+                else config['site_name'],
             "ttl": self.config.feed_ttl,
         }
 

tests/fixtures/mkdocs_custom_title_description.yml

@@ -0,0 +1,11 @@
+site_name: Test RSS Plugin with custom titles and descriptions
+site_description: Test RSS Plugin with customized descriptions
+site_url: https://guts.github.io/mkdocs-rss-plugin
+
+plugins:
+  - rss:
+      title: My custom RSS title
+      description: My custom RSS description
+
+theme:
+  name: mkdocs

tests/test_build.py

@@ -657,6 +657,25 @@ def test_simple_build_pretty_print_disabled(self):
             with Path(Path(tmpdirname) / OUTPUT_RSS_FEED_UPDATED).open("r") as f:
                 self.assertEqual(len(f.readlines()), 1)
 
+    def test_simple_build_custome_title_description(self):
+        with tempfile.TemporaryDirectory() as tmpdirname:
+            cli_result = self.build_docs_setup(
+                testproject_path="docs",
+                mkdocs_yml_filepath=Path("tests/fixtures/mkdocs_custom_title_description.yml"),
+                output_path=tmpdirname,
+            )
+            if cli_result.exception is not None:
+                e = cli_result.exception
+                logger.debug(format_exception(type(e), e, e.__traceback__))
+
+            self.assertEqual(cli_result.exit_code, 0)
+            self.assertIsNone(cli_result.exception)
+
+            # created items
+            feed_parsed = feedparser.parse(Path(tmpdirname) / OUTPUT_RSS_FEED_CREATED)
+            self.assertEqual(feed_parsed.feed.title, "My custom RSS title")
+            self.assertEqual(feed_parsed.feed.description, "My custom RSS description")
+
     def test_rss_feed_validation(self):
         with tempfile.TemporaryDirectory() as tmpdirname:
             cli_result = self.build_docs_setup(

tests/test_config.py

@@ -70,6 +70,7 @@ def test_plugin_config_defaults(self):
                 "default_time": datetime.min.strftime("%H:%M"),
                 "default_timezone": "UTC",
             },
+            "description": "",
             "enabled": True,
             "feed_ttl": 1440,
             "image": None,
@@ -84,6 +85,7 @@ def test_plugin_config_defaults(self):
             },
             "pretty_print": False,
             "rss_feed_enabled": True,
+            "title": "",
             "url_parameters": None,
             "use_git": True,
             "use_material_social_cards": True,
@@ -112,6 +114,7 @@ def test_plugin_config_image(self):
                 "default_time": datetime.min.strftime("%H:%M"),
                 "default_timezone": "UTC",
             },
+            "description": "",
             "enabled": True,
             "feed_ttl": 1440,
             "image": self.feed_image,
@@ -126,6 +129,7 @@ def test_plugin_config_image(self):
             },
             "pretty_print": False,
             "rss_feed_enabled": True,
+            "title": "",
             "url_parameters": None,
             "use_git": True,
             "use_material_social_cards": True,