diff --git a/docs/configuration.md b/docs/configuration.md index 1515e59..e4a7120 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -173,12 +173,32 @@ Default: `true`. Used, in combination with `abstract_delimiter`, to determine each [item description element](https://www.w3schools.com/xml/rss_tag_title_link_description_item.asp): - If this value is set to `-1`, then the articles' full HTML content will be filled into the description element. +- If you want to customize the description per each Markdown page, refer to the example below. - Otherwise, the plugin first tries to retrieve the value of the keyword `description` from the [page metadata]. - If that fails and `abstract_delimiter` is found in the page, the article content up to (but not including) the delimiter is used. - If the above has failed, then the plugin retrieves the first number of characters of the page content defined by this setting. Retrieved content is the raw markdown converted roughly into HTML. Be careful: if set to `0` and there is no description, the feed's compliance is broken (an item must have a description). +#### Override feed description per page + +To customize the value of the RSS description per each page and override the value of `site_description` and `plugins.rss.feed_description`, you can modify the value per each page as you see in the example below: + +```markdown +--- +date: 2024-06-24 +description: >- + This is the SEO description. +social: + cards_layout_options: + description: >- + This is the social cards description. +rss: + feed_description: >- + And I want to have customized RSS description. +--- +``` + `abstract_chars_count`: number of characters to use as item description. Default: `150` diff --git a/mkdocs_rss_plugin/util.py b/mkdocs_rss_plugin/util.py index d34e7bc..df00c72 100644 --- a/mkdocs_rss_plugin/util.py +++ b/mkdocs_rss_plugin/util.py @@ -498,7 +498,10 @@ def get_description_or_abstract( Returns: str: page description to use """ - description = in_page.meta.get("description") + if in_page.meta.get("rss", {}).get("feed_description"): + description = in_page.meta["rss"]["feed_description"] + else: + description = in_page.meta.get("description") # If the full page is wanted (unlimited chars count) if chars_count == -1 and (in_page.content or in_page.markdown): diff --git a/tests/fixtures/docs/page_with_meta_override_rss_description.md b/tests/fixtures/docs/page_with_meta_override_rss_description.md new file mode 100644 index 0000000..b5aa557 --- /dev/null +++ b/tests/fixtures/docs/page_with_meta_override_rss_description.md @@ -0,0 +1,19 @@ +--- +title: Page with overridden rss feed description +authors: + - Guts + - Tim Vink + - liang2kl +date: 2020-03-20 10:20 +update: 2022-03-30 10:20 +description: First test page of mkdocs-rss-plugin test suite +image: "https://svgsilh.com/png-512/97849.png" +rss: + feed_description: This is a custom override of the feed description +tags: + - test +--- + +# Test page with meta + +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. diff --git a/tests/test_build.py b/tests/test_build.py index 3342ed5..78ac477 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -679,6 +679,40 @@ def test_simple_build_custom_title_description(self): self.assertEqual(feed_parsed.feed.title, "My custom RSS title") self.assertEqual(feed_parsed.feed.description, "My custom RSS description") + def test_simple_build_override_per_page_rss_feed_description(self): + """ + Test per-page rss.feed_description overrides the config site_description and rss.feed_description + + How to run this test: + pytest tests/test_build.py::TestBuildRss::test_simple_build_override_per_page_rss_feed_description + """ + 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) + for feed_item in feed_parsed.entries: + if feed_item.title == "Page with overridden rss feed description": + self.assertEqual( + feed_item.description, + "This is a custom override of the feed description", + ) + break + else: + self.fail("Page with overridden rss feed description not found") + def test_rss_feed_validation(self): with tempfile.TemporaryDirectory() as tmpdirname: cli_result = self.build_docs_setup(