small formatting & naming updates

Addresses @Guts suggestions. Thanks!

Author: toomanybrians

README.md

@@ -53,21 +53,21 @@ 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
+      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
       length: 20
       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,9 +367,9 @@ At the end, into the RSS you will get:
 
 ----
 
-### :material-subtitles: `description`: override site description { #description }
+### :material-subtitles: `feed_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 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.)
 
@@ -378,13 +378,45 @@ This setting is optional. If you do not include it, the default site description
 ```yaml
 plugins:
   - rss:
-      description: The best blog from the best site
+      feed_description: The best blog from the best site
 ```
 
 Default: Use the default MkDocs `site_description:`.
 
 ----
 
+### :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:`.
+
+----
+
+### :material-clock-end: `feed_ttl`: feed's cache time { #feed_ttl }
+
+`feed_ttl`: number of minutes to be cached. Inserted as channel `ttl` element. See: [W3C RSS 2.0 documentation](https://www.w3schools.com/xml/rss_tag_ttl.asp).
+
+Default: `1440` (= 1 day)
+
+Output:
+
+```xml
+<ttl>1440</ttl>
+```
+
+----
+
 ### :material-alphabet-latin: `feeds_filenames`: customize the output feed URL { #feeds_filenames }
 
 > Since version 1.13.0.
@@ -410,20 +442,6 @@ Default:
 
 ----
 
-### :material-clock-end: `feed_ttl`: feed's cache time { #feed_ttl }
-
-`feed_ttl`: number of minutes to be cached. Inserted as channel `ttl` element. See: [W3C RSS 2.0 documentation](https://www.w3schools.com/xml/rss_tag_ttl.asp).
-
-Default: `1440` (= 1 day)
-
-Output:
-
-```xml
-<ttl>1440</ttl>
-```
-
-----
-
 ### :material-image-outline: `image`: set the channel image { #image }
 
 `image`: URL to image to use as feed illustration.
@@ -496,24 +514,6 @@ 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).

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

@@ -44,17 +44,17 @@ 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)
+    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)
     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

@@ -116,9 +116,9 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig:
             "buildDate": formatdate(get_build_timestamp()),
             "copyright": config.copyright,
             "description": (
-                self.config["description"]
-                if self.config["description"]
-                else config["site_description"]
+                self.config.feed_description
+                if self.config.feed_description
+                else config.site_description
             ),
             "entries": [],
             "generator": f"{__title__} - v{__version__}",
@@ -127,7 +127,7 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig:
             "pubDate": formatdate(get_build_timestamp()),
             "repo_url": config.repo_url,
             "title": (
-                self.config["title"] if self.config["title"] else config["site_name"]
+                self.config.feed_title if self.config.feed_title else config.site_name
             ),
             "ttl": self.config.feed_ttl,
         }

tests/fixtures/mkdocs_custom_title_description.yml

@@ -4,8 +4,8 @@ site_url: https://guts.github.io/mkdocs-rss-plugin
 
 plugins:
   - rss:
-      title: My custom RSS title
-      description: My custom RSS description
+      feed_title: My custom RSS title
+      feed_description: My custom RSS description
 
 theme:
   name: mkdocs

tests/test_build.py

@@ -657,7 +657,8 @@ 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):
+    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",

tests/test_config.py

@@ -70,8 +70,9 @@ def test_plugin_config_defaults(self):
                 "default_time": datetime.min.strftime("%H:%M"),
                 "default_timezone": "UTC",
             },
-            "description": "",
             "enabled": True,
+            "feed_description": None,
+            "feed_title": None,
             "feed_ttl": 1440,
             "image": None,
             "json_feed_enabled": True,
@@ -85,7 +86,6 @@ 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,
@@ -114,8 +114,9 @@ def test_plugin_config_image(self):
                 "default_time": datetime.min.strftime("%H:%M"),
                 "default_timezone": "UTC",
             },
-            "description": "",
             "enabled": True,
+            "feed_description": None,
+            "feed_title": None,
             "feed_ttl": 1440,
             "image": self.feed_image,
             "json_feed_enabled": True,
@@ -129,7 +130,6 @@ 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,