diff --git a/README.md b/README.md index 5b195e3..83b8300 100644 --- a/README.md +++ b/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 diff --git a/docs/configuration.md b/docs/configuration.md index a869404..0f53989 100644 --- a/docs/configuration.md +++ b/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. diff --git a/docs/index.md b/docs/index.md index 8a2f487..3b0eba2 100644 --- a/docs/index.md +++ b/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) diff --git a/mkdocs_rss_plugin/config.py b/mkdocs_rss_plugin/config.py index 49d7482..40c0ddc 100644 --- a/mkdocs_rss_plugin/config.py +++ b/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) diff --git a/mkdocs_rss_plugin/integrations/theme_material_social_plugin.py b/mkdocs_rss_plugin/integrations/theme_material_social_plugin.py index 5e43b77..e8b76a0 100644 --- a/mkdocs_rss_plugin/integrations/theme_material_social_plugin.py +++ b/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. diff --git a/mkdocs_rss_plugin/plugin.py b/mkdocs_rss_plugin/plugin.py index 0d5f873..8d3d07c 100644 --- a/mkdocs_rss_plugin/plugin.py +++ b/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, } diff --git a/mkdocs_rss_plugin/util.py b/mkdocs_rss_plugin/util.py index b320621..0dd41ad 100644 --- a/mkdocs_rss_plugin/util.py +++ b/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 diff --git a/tests/base.py b/tests/base.py index a5b5151..a339c76 100644 --- a/tests/base.py +++ b/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 diff --git a/tests/fixtures/mkdocs_custom_title_description.yml b/tests/fixtures/mkdocs_custom_title_description.yml new file mode 100644 index 0000000..de957c8 --- /dev/null +++ b/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 diff --git a/tests/test_build.py b/tests/test_build.py index 3dcef84..691eeb6 100644 --- a/tests/test_build.py +++ b/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( diff --git a/tests/test_config.py b/tests/test_config.py index db5847a..f1d2964 100644 --- a/tests/test_config.py +++ b/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,