feature(option): allow customize output filenames (#278)

Add option `feeds_filenames` to 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`
Guts · Jun 8, 2024 · 9e7369e · 9e7369e
2 parents c5c3759 + 222d3f0
commit 9e7369e
Show file tree

Hide file tree

Showing 8 changed files with 141 additions and 47 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -415,6 +415,33 @@ At the end, into the RSS you will get:
         - for Python >= 3.9, it uses the standard library and ships [tzdata](https://pypi.org/project/tzdata/) only on Windows which do not provide such data
         - for Python < 3.9, [pytz](https://pypi.org/project/pytz/) is shipped.
 
+----
+
+### `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`
+
+----
+
 ### `pretty_print`: prettified XML
 
 By default, the output file is minified, using Jinja2 strip options and manual work. It's possible to disable it and prettify the output using `pretty_print: true`.

diff --git a/mkdocs_rss_plugin/config.py b/mkdocs_rss_plugin/config.py
@@ -9,10 +9,18 @@
 from mkdocs.config import config_options
 from mkdocs.config.base import Config
 
-
 # ############################################################################
 # ########## Classes ###############
 # ##################################
+
+
+class _FeedsFilenamesConfig(Config):
+    json_created = config_options.Type(str, default="feed_json_created.json")
+    json_updated = config_options.Type(str, default="feed_json_updated.json")
+    rss_created = config_options.Type(str, default="feed_rss_created.xml")
+    rss_updated = config_options.Type(str, default="feed_rss_updated.xml")
+
+
 class RssPluginConfig(Config):
     """Configuration for RSS plugin for Mkdocs."""
 
@@ -29,6 +37,7 @@ class RssPluginConfig(Config):
     json_feed_enabled = config_options.Type(bool, default=True)
     length = config_options.Type(int, default=20)
     match_path = config_options.Type(str, default=".*")
+    feeds_filenames = config_options.SubConfig(_FeedsFilenamesConfig)
     pretty_print = config_options.Type(bool, default=False)
     rss_feed_enabled = config_options.Type(bool, default=True)
     url_parameters = config_options.Optional(config_options.Type(dict))

diff --git a/mkdocs_rss_plugin/constants.py b/mkdocs_rss_plugin/constants.py
@@ -17,10 +17,6 @@
 DEFAULT_TEMPLATE_FOLDER = Path(__file__).parent / "templates"
 DEFAULT_TEMPLATE_FILENAME = DEFAULT_TEMPLATE_FOLDER / "rss.xml.jinja2"
 MKDOCS_LOGGER_NAME = "[RSS-plugin]"
-OUTPUT_RSS_FEED_CREATED = "feed_rss_created.xml"
-OUTPUT_RSS_FEED_UPDATED = "feed_rss_updated.xml"
-OUTPUT_JSON_FEED_CREATED = "feed_json_created.json"
-OUTPUT_JSON_FEED_UPDATED = "feed_json_updated.json"
 REMOTE_REQUEST_HEADERS = {
     "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
     "User-Agent": f"{__about__.__title__}/{__about__.__version__}",

diff --git a/mkdocs_rss_plugin/models.py b/mkdocs_rss_plugin/models.py
@@ -7,7 +7,7 @@
 # standard
 from datetime import datetime
 from pathlib import Path
-from typing import NamedTuple
+from typing import NamedTuple, Optional
 
 
 # ############################################################################
@@ -16,14 +16,14 @@
 class PageInformation(NamedTuple):
     """Data type to set and get page information in order to produce the RSS feed."""
 
-    abs_path: Path = None
-    categories: list = None
-    authors: tuple = None
-    created: datetime = None
-    description: str = None
-    guid: str = None
-    image: str = None
-    title: str = None
-    updated: datetime = None
-    url_comments: str = None
-    url_full: str = None
+    abs_path: Optional[Path] = None
+    categories: Optional[list] = None
+    authors: Optional[tuple] = None
+    created: Optional[datetime] = None
+    description: Optional[str] = None
+    guid: Optional[str] = None
+    image: Optional[str] = None
+    title: Optional[str] = None
+    updated: Optional[datetime] = None
+    url_comments: Optional[str] = None
+    url_full: Optional[str] = None
diff --git a/mkdocs_rss_plugin/plugin.py b/mkdocs_rss_plugin/plugin.py
@@ -28,10 +28,6 @@
     DEFAULT_TEMPLATE_FILENAME,
     DEFAULT_TEMPLATE_FOLDER,
     MKDOCS_LOGGER_NAME,
-    OUTPUT_JSON_FEED_CREATED,
-    OUTPUT_JSON_FEED_UPDATED,
-    OUTPUT_RSS_FEED_CREATED,
-    OUTPUT_RSS_FEED_UPDATED,
 )
 from mkdocs_rss_plugin.integrations.theme_material_social_plugin import (
     IntegrationMaterialSocialCards,
@@ -82,7 +78,6 @@ def on_config(self, config: config_options.Config) -> dict:
         :return: plugin configuration object
         :rtype: dict
         """
-
         # Skip if disabled
         if not self.config.enabled:
             return config
@@ -121,8 +116,8 @@ def on_config(self, config: config_options.Config) -> dict:
             "description": config.site_description,
             "entries": [],
             "generator": f"{__title__} - v{__version__}",
-            "html_url": self.util.get_site_url(config),
-            "language": self.util.guess_locale(config),
+            "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,
@@ -185,16 +180,16 @@ def on_config(self, config: config_options.Config) -> dict:
         if base_feed.get("html_url"):
             # concatenate both URLs
             self.feed_created["rss_url"] = (
-                base_feed.get("html_url") + OUTPUT_RSS_FEED_CREATED
+                base_feed.get("html_url") + self.config.feeds_filenames.rss_created
             )
             self.feed_updated["rss_url"] = (
-                base_feed.get("html_url") + OUTPUT_RSS_FEED_UPDATED
+                base_feed.get("html_url") + self.config.feeds_filenames.rss_updated
             )
             self.feed_created["json_url"] = (
-                base_feed.get("html_url") + OUTPUT_JSON_FEED_CREATED
+                base_feed.get("html_url") + self.config.feeds_filenames.json_created
             )
             self.feed_updated["json_url"] = (
-                base_feed.get("html_url") + OUTPUT_JSON_FEED_UPDATED
+                base_feed.get("html_url") + self.config.feeds_filenames.json_updated
             )
         else:
             logger.error(
@@ -210,7 +205,7 @@ def on_config(self, config: config_options.Config) -> dict:
     @event_priority(priority=-75)
     def on_page_content(
         self, html: str, page: Page, config: config_options.Config, files
-    ) -> str:
+    ) -> Optional[str]:
         """The page_content event is called after the Markdown text is rendered
         to HTML (but before being passed to a template) and can be used to alter
         the HTML body of the page.
@@ -299,7 +294,7 @@ def on_page_content(
             )
         )
 
-    def on_post_build(self, config: config_options.Config) -> dict:
+    def on_post_build(self, config: config_options.Config) -> Optional[dict]:
         """The post_build event does not alter any variables. \
         Use this event to call post-build scripts. \
         See: <https://www.mkdocs.org/user-guide/plugins/#on_post_build>
@@ -318,10 +313,18 @@ def on_post_build(self, config: config_options.Config) -> dict:
         pretty_print = self.config.pretty_print
 
         # output filepaths
-        out_feed_created = Path(config.site_dir).joinpath(OUTPUT_RSS_FEED_CREATED)
-        out_feed_updated = Path(config.site_dir).joinpath(OUTPUT_RSS_FEED_UPDATED)
-        out_json_created = Path(config.site_dir).joinpath(OUTPUT_JSON_FEED_CREATED)
-        out_json_updated = Path(config.site_dir).joinpath(OUTPUT_JSON_FEED_UPDATED)
+        out_feed_created = Path(config.site_dir).joinpath(
+            self.config.feeds_filenames.rss_created
+        )
+        out_feed_updated = Path(config.site_dir).joinpath(
+            self.config.feeds_filenames.rss_updated
+        )
+        out_json_created = Path(config.site_dir).joinpath(
+            self.config.feeds_filenames.json_created
+        )
+        out_json_updated = Path(config.site_dir).joinpath(
+            self.config.feeds_filenames.json_updated
+        )
 
         # created items
         self.feed_created.get("entries").extend(

diff --git a/tests/fixtures/mkdocs_custom_feeds_filenames.yml b/tests/fixtures/mkdocs_custom_feeds_filenames.yml
@@ -0,0 +1,14 @@
+site_name: Test RSS Plugin with custom RSS and JSON feeds output
+site_description: Test RSS Plugin with customized output_basename
+site_url: https://guts.github.io/mkdocs-rss-plugin
+
+plugins:
+  - rss:
+      feeds_filenames:
+        json_created: json
+        json_updated: json-updated
+        rss_created: rss
+        rss_updated: rss-updated
+
+theme:
+  name: mkdocs
diff --git a/tests/test_build.py b/tests/test_build.py
@@ -15,31 +15,27 @@
 
 # Standard library
 import json
+import logging
 import tempfile
 import unittest
-
-# logging
-from logging import DEBUG, getLogger
 from pathlib import Path
 from traceback import format_exception
 
 # 3rd party
 import feedparser
 import jsonfeed
 
-# project
-from mkdocs_rss_plugin.constants import (
-    OUTPUT_JSON_FEED_CREATED,
-    OUTPUT_JSON_FEED_UPDATED,
-    OUTPUT_RSS_FEED_CREATED,
-    OUTPUT_RSS_FEED_UPDATED,
-)
-
 # test suite
 from tests.base import BaseTest
 
-logger = getLogger(__name__)
-logger.setLevel(DEBUG)
+# -- Globals --
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+
+OUTPUT_RSS_FEED_CREATED = "feed_rss_created.xml"
+OUTPUT_RSS_FEED_UPDATED = "feed_rss_updated.xml"
+OUTPUT_JSON_FEED_CREATED = "feed_json_created.json"
+OUTPUT_JSON_FEED_UPDATED = "feed_json_updated.json"
 
 # #############################################################################
 # ########## Classes ###############
@@ -531,6 +527,43 @@ def test_simple_build_language_specific_material(self):
             feed_parsed = feedparser.parse(Path(tmpdirname) / OUTPUT_RSS_FEED_UPDATED)
             self.assertEqual(feed_parsed.feed.get("language"), "fr")
 
+    def test_simple_build_custom_output_basename(self):
+        config = self.get_plugin_config_from_mkdocs(
+            mkdocs_yml_filepath=Path(
+                "tests/fixtures/mkdocs_custom_feeds_filenames.yml"
+            ),
+            plugin_name="rss",
+        )
+
+        with tempfile.TemporaryDirectory() as tmpdirname:
+            cli_result = self.build_docs_setup(
+                testproject_path="docs",
+                mkdocs_yml_filepath=Path(
+                    "tests/fixtures/mkdocs_custom_feeds_filenames.yml"
+                ),
+                output_path=tmpdirname,
+                strict=True,
+            )
+
+            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) / config.feeds_filenames.rss_created
+            )
+            self.assertEqual(feed_parsed.bozo, 0)
+
+            # updated items
+            feed_parsed = feedparser.parse(
+                Path(tmpdirname) / config.feeds_filenames.rss_updated
+            )
+            self.assertEqual(feed_parsed.bozo, 0)
+
     def test_simple_build_pretty_print_enabled(self):
         with tempfile.TemporaryDirectory() as tmpdirname:
             cli_result = self.build_docs_setup(

diff --git a/tests/test_config.py b/tests/test_config.py
@@ -69,6 +69,12 @@ def test_plugin_config_defaults(self):
             "json_feed_enabled": True,
             "length": 20,
             "match_path": ".*",
+            "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",
+            },
             "pretty_print": False,
             "rss_feed_enabled": True,
             "url_parameters": None,
@@ -99,6 +105,12 @@ def test_plugin_config_image(self):
             "json_feed_enabled": True,
             "length": 20,
             "match_path": ".*",
+            "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",
+            },
             "pretty_print": False,
             "rss_feed_enabled": True,
             "url_parameters": None,