Feature: add per-feed custom titles and abstracts (#295)

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:

``` yaml

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)

Author: Guts

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(