Feature: add per-feed custom titles and abstracts

README.md

@@ -54,11 +54,13 @@ plugins:
         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

docs/configuration.md

@@ -367,28 +367,39 @@ At the end, into the RSS you will get:
 
 ----
 
-### :material-alphabet-latin: `feeds_filenames`: customize the output feed URL { #feeds_filenames }
+### :material-subtitles: `feed_description`: override site description { #description }
 
-> Since version 1.13.0.
+This option allows you to override the default MkDocs site description for the description tag in this 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.)
 
-Customize every feed filenames generated by the plugin:
+This setting is optional. If you do not include it, the default site description will be used.
 
-```yaml title="mkdocs.yml with custom RSS and JSON feeds names."
+```yaml
 plugins:
   - rss:
-      feeds_filenames:
-        json_created: feed.json
-        json_updated: feed-updated.json
-        rss_created: rss.xml
-        rss_updated: rss-updated.xml
+      feed_description: The best blog from the best site
 ```
 
-Default:
+Default: Use the default MkDocs `site_description:`.
 
-- JSON feed for **created** items: `feed_json_created.json`
-- JSON feed for **updated** items: `feed_json_updated.json`
-- RSS feed for **created** items: `feed_rss_created.json`
-- RSS feed for **updated** items: `feed_rss_updated.json`
+----
+
+### :material-format-title: `feed_title`: override site title { #title }
+
+This option allows you to override the default MkDocs site name for the title tag in this 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:
+      feed_title: My awesome blog feed
+```
+
+Default: Use the default MkDocs `site_name:`.
 
 ----
 
@@ -406,6 +417,31 @@ Output:
 
 ----
 
+### :material-alphabet-latin: `feeds_filenames`: customize the output feed URL { #feeds_filenames }
+
+> Since version 1.13.0.
+
+Customize every feed filenames generated by the plugin:
+
+```yaml title="mkdocs.yml with custom RSS and JSON feeds names."
+plugins:
+  - rss:
+      feeds_filenames:
+        json_created: feed.json
+        json_updated: feed-updated.json
+        rss_created: rss.xml
+        rss_updated: rss-updated.xml
+```
+
+Default:
+
+- JSON feed for **created** items: `feed_json_created.json`
+- JSON feed for **updated** items: `feed_json_updated.json`
+- RSS feed for **created** items: `feed_rss_created.json`
+- RSS feed for **updated** items: `feed_rss_updated.json`
+
+----
+
 ### :material-image-outline: `image`: set the channel image { #image }
 
 `image`: URL to image to use as feed illustration.

docs/index.md

@@ -54,7 +54,7 @@ plugins:
 
 ## Example
 
-As examples, here come the feeds generated for this documentation:
+As examples, here are the feeds generated for this documentation:
 
 - [feed_rss_created.xml](feed_rss_created.xml) and [feed_json_created.json](feed_json_created.json) for  latest **created** pages: [W3C validator](https://validator.w3.org/feed/check.cgi?url=https%3A//guts.github.io/mkdocs-rss-plugin/feed_rss_created.xml)
 - [feed_rss_updated.xml](feed_rss_updated.xml) and [feed_json_updated.json](feed_json_updated.json) for latest **updated** pages: [W3C validator](https://validator.w3.org/feed/check.cgi?url=https%3A//guts.github.io/mkdocs-rss-plugin/feed_rss_updated.xml)

mkdocs_rss_plugin/config.py

@@ -45,8 +45,10 @@ class RssPluginConfig(Config):
     comments_path = config_options.Optional(config_options.Type(str))
     date_from_meta = config_options.SubConfig(_DateFromMeta)
     enabled = config_options.Type(bool, default=True)
-    feed_ttl = config_options.Type(int, default=1440)
     feeds_filenames = config_options.SubConfig(_FeedsFilenamesConfig)
+    feed_description = config_options.Optional(config_options.Type(str))
+    feed_title = config_options.Optional(config_options.Type(str))
+    feed_ttl = config_options.Type(int, default=1440)
     image = config_options.Optional(config_options.Type(str))
     json_feed_enabled = config_options.Type(bool, default=True)
     length = config_options.Type(int, default=20)

mkdocs_rss_plugin/integrations/theme_material_social_plugin.py

@@ -44,7 +44,7 @@ class IntegrationMaterialSocialCards:
     CARDS_MANIFEST: dict | None = None
 
     def __init__(self, mkdocs_config: MkDocsConfig, switch_force: bool = True) -> None:
-        """Integration instanciation.
+        """Integration instantiation.
 
         Args:
             mkdocs_config (MkDocsConfig): 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.feed_description
+                if self.config.feed_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.feed_title if self.config.feed_title else config.site_name
+            ),
             "ttl": self.config.feed_ttl,
         }
 

mkdocs_rss_plugin/util.py

@@ -669,7 +669,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:
+      feed_title: My custom RSS title
+      feed_description: My custom RSS description
+
+theme:
+  name: mkdocs

tests/test_build.py

@@ -657,6 +657,28 @@ 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_custom_title_description(self):
+        """Test simple build with custom description and title."""
+        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

@@ -71,6 +71,8 @@ def test_plugin_config_defaults(self):
                 "default_timezone": "UTC",
             },
             "enabled": True,
+            "feed_description": None,
+            "feed_title": None,
             "feed_ttl": 1440,
             "image": None,
             "json_feed_enabled": True,
@@ -113,6 +115,8 @@ def test_plugin_config_image(self):
                 "default_timezone": "UTC",
             },
             "enabled": True,
+            "feed_description": None,
+            "feed_title": None,
             "feed_ttl": 1440,
             "image": self.feed_image,
             "json_feed_enabled": True,