diff --git a/docs/configuration.md b/docs/configuration.md index ca612e1..c95b99d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -550,6 +550,38 @@ Default: `False`. ---- +### :material-brush-variant: `stylesheet`: define a XSL stylesheet { #stylesheet } + +Use a XSL stylesheet to customize how the RSS feed looks like. `auto` is a special value to use the stylesheet shipped with the plugin. + +```yaml +plugins: + - rss: + stylesheet: auto +``` + +If you're willing to work on your own stylesheet, set the URL or relative path: + +```yaml +plugins: + - rss: + stylesheet: https://docs.example.org/rss_stylesheet.xsl +``` + +Note that it's recommended to host the stylesheet on the same website / domain to make CORS happy. + +If you prefer to disable the stylesheet, you set it to `""`: + +```yaml +plugins: + - rss: + stylesheet: "" +``` + +Default: `auto`. + +---- + ### :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). diff --git a/mkdocs.yml b/mkdocs.yml index 78d265c..34a4df0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -121,6 +121,7 @@ plugins: match_path: ".*" pretty_print: true rss_feed_enabled: true + stylesheet: auto url_parameters: utm_source: "documentation" utm_medium: "RSS" diff --git a/mkdocs_rss_plugin/config.py b/mkdocs_rss_plugin/config.py index bc37a95..8f0327f 100644 --- a/mkdocs_rss_plugin/config.py +++ b/mkdocs_rss_plugin/config.py @@ -58,6 +58,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) + stylesheet = config_options.Type(str, default="auto") url_parameters = config_options.Optional(config_options.Type(dict)) use_git = config_options.Type(bool, default=True) use_material_blog = config_options.Type(bool, default=True) diff --git a/mkdocs_rss_plugin/models.py b/mkdocs_rss_plugin/models.py index 2b458e5..6c433ab 100644 --- a/mkdocs_rss_plugin/models.py +++ b/mkdocs_rss_plugin/models.py @@ -90,5 +90,6 @@ class RssFeedBase: pubDate: str | None = None repo_url: str | None = None rss_url: str | None = None + stylesheet: str | None = None title: str | None = None ttl: int | None = None diff --git a/mkdocs_rss_plugin/plugin.py b/mkdocs_rss_plugin/plugin.py index 8383b80..1a1a2a3 100644 --- a/mkdocs_rss_plugin/plugin.py +++ b/mkdocs_rss_plugin/plugin.py @@ -12,6 +12,7 @@ from email.utils import format_datetime, formatdate from pathlib import Path from re import compile as re_compile +from shutil import copyfile from typing import Literal # 3rd party @@ -175,6 +176,23 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig: if self.config.image: base_feed.logo_url = self.config.image + # feed stylesheet (XSL) + print(f"Config stylesheet: {self.config.stylesheet}") + if self.config.stylesheet: + if self.config.stylesheet == "auto": + base_feed.stylesheet = "rss.xsl" + logger.debug( + f"Shipped stylesheet will be referenced in RSS feeds: {self.config.stylesheet}" + ) + else: + + base_feed.stylesheet = self.config.stylesheet + logger.debug( + f"Stylesheet will be referenced in RSS feeds: {self.config.stylesheet}" + ) + else: + logger.debug("No stylesheet will be referenced in RSS feeds.") + # pattern to match pages included in output self.match_path_pattern = re_compile(self.config.match_path) @@ -378,6 +396,12 @@ def on_post_build(self, config: config_options.Config) -> None: self.config.feeds_filenames.json_updated ) + # stylesheet for RSS feed + if self.config.stylesheet == "auto": + xsl_source = self.tpl_folder.joinpath("default.xsl") + xsl_dest = Path(config.site_dir).joinpath("rss.xsl") + copyfile(xsl_source, xsl_dest) + # created items self.feed_created.entries.extend( self.util.filter_pages( diff --git a/mkdocs_rss_plugin/templates/default.xsl b/mkdocs_rss_plugin/templates/default.xsl new file mode 100644 index 0000000..e56bc17 --- /dev/null +++ b/mkdocs_rss_plugin/templates/default.xsl @@ -0,0 +1,188 @@ + + + + + + + + + + + <xsl:value-of select="rss/channel/title"/> + + + + + + +
+ + + + + + 64 + + + +

+ +

+ +

+ +

+ +

+ + + + + Visit website + +

+
+ + + By + + + + — Published: + + + + + — Updated: + + + +
+
+ + + +
+ +

+ + + + + + +

+ +
+ + Par + + + — + +
+ + + + + + + + + + +

+ +

+ +
+ + + + + +
+ +
+ + + + + + + + diff --git a/mkdocs_rss_plugin/templates/rss.xml.jinja2 b/mkdocs_rss_plugin/templates/rss.xml.jinja2 index 65d9726..5328672 100644 --- a/mkdocs_rss_plugin/templates/rss.xml.jinja2 +++ b/mkdocs_rss_plugin/templates/rss.xml.jinja2 @@ -1,4 +1,5 @@ +{% if feed.stylesheet is not none %}{% endif -%} {# Mandatory elements #} diff --git a/tests/fixtures/mkdocs_stylesheet_disabled.yml b/tests/fixtures/mkdocs_stylesheet_disabled.yml new file mode 100644 index 0000000..704638c --- /dev/null +++ b/tests/fixtures/mkdocs_stylesheet_disabled.yml @@ -0,0 +1,12 @@ +site_name: Test RSS Plugin - Disable stylesheet +# site_description: Test RSS Plugin +site_url: https://guts.github.io/mkdocs-rss-plugin + +use_directory_urls: true + +plugins: + - rss: + stylesheet: "" + +theme: + name: mkdocs diff --git a/tests/test_config.py b/tests/test_config.py index 17200ea..77d7aa4 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -88,6 +88,7 @@ def test_plugin_config_defaults(self): "rss_updated": "feed_rss_updated.xml", }, "pretty_print": False, + "stylesheet": "auto", "rss_feed_enabled": True, "url_parameters": None, "use_git": True, @@ -134,6 +135,7 @@ def test_plugin_config_image(self): "rss_updated": "feed_rss_updated.xml", }, "pretty_print": False, + "stylesheet": "auto", "rss_feed_enabled": True, "url_parameters": None, "use_git": True,