Feature: add per-feed custom titles and abstracts

README.md

@@ -53,6 +53,7 @@ plugins:
         datetime_format: "%Y-%m-%d %H:%M"
         default_time: "09:30"
         default_timezone: Europe/Paris
+      description: "My custom feed description"  # MkDocs site_description: will be used if this key is not present
       enabled: true
       feeds_filenames:
         json_created: feed_json_created.json
@@ -66,6 +67,7 @@ plugins:
       match_path: ".*"
       pretty_print: false
       rss_feed_enabled: true
+      title: "My custom feed title"  # MkDocs site_name: will be used if this key is not present
       url_parameters:
         utm_source: "documentation"
         utm_medium: "RSS"

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 name will be used.
+
+```yaml
+plugins:
+  - rss:
+      title: My awesome blog feed
+```
+
+Default: Use the default MkDocs `site_name:`.
+
+----
+
 ### :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/integrations/theme_material_social_plugin.py

@@ -34,7 +34,7 @@ class IntegrationMaterialSocialCards:
     IS_THEME_MATERIAL: bool = False
 
     def __init__(self, mkdocs_config: Config, switch_force: bool = True) -> None:
-        """Integration instanciation.
+        """Integration instantiation.
 
         Args:
             mkdocs_config (Config): Mkdocs website configuration object.

mkdocs_rss_plugin/plugin.py

@@ -56,7 +56,7 @@ class GitRssPlugin(BasePlugin[RssPluginConfig]):
     supports_multiple_instances = True
 
     def __init__(self):
-        """Instanciation."""
+        """Instantiation."""
         # pages storage
         self.pages_to_filter: list = []
         # prepare output feeds
@@ -98,7 +98,7 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig:
             switch_force=self.config.use_material_social_cards,
         )
 
-        # instanciate plugin tooling
+        # instantiate plugin tooling
         self.util = Util(
             use_git=self.config.use_git,
             integration_material_social_cards=self.integration_material_social_cards,
@@ -115,14 +115,20 @@ 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,
         }
 

mkdocs_rss_plugin/util.py

@@ -668,7 +668,7 @@ def get_site_url(mkdocs_config: MkDocsConfig) -> str | None:
         :rtype: str or None
         """
         # this method exists because the following line returns an empty string instead of \
-        # None (because the key alwayus exists)
+        # None (because the key always exists)
         defined_site_url = mkdocs_config.site_url
 
         # cases

tests/base.py

@@ -45,7 +45,7 @@ def get_plugin_config_from_mkdocs(
         not enabled into the mkdocs.yml.
         :rtype: Config
         """
-        # instanciate plugin
+        # instantiate plugin
         cfg_mkdocs = load_config(str(mkdocs_yml_filepath.resolve()))
 
         plugins = cfg_mkdocs.plugins

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,27 @@ 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,