feat: allow per-page description customization (#310)

Hello @Guts 

Thanks for the awesome project.

I use this plugin heavily in my [SRE
blog](https://developer-friendly.blog).

I figured it would be nice to allow per page customization of the
`description` field, cause at the moment, there's not a lot one can do
when the description before `<!-- more -->` is short and extra detail is
desired.

With this change, you can have separate contents for RSS description and
your typical content.

An example taken from the [Material for Mkdocs Social
Cards](https://squidfunk.github.io/mkdocs-material/plugins/social/#option.description):

```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.
---

```


This idea, I reckon, can easily be extended for other similar use-cases:
- #297 
- #275 
- #197

Author: Guts

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`

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):

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.

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(