From ada0a8d85664376ccec6cf345ae5c37c5616325b Mon Sep 17 00:00:00 2001
From: Zerthick <zerthick@gmail.com>
Date: Sun, 9 Aug 2026 23:11:39 -0700
Subject: [PATCH] fix: resolve double-encoded HTML entities in title and
 description

MkDocs pre-escapes content, then Jinja's |e filter escapes again,
producing &amp;amp;, &amp;lt;, &amp;gt;. Use html.unescape() in Python
before template rendering so |e performs a single correct escape.

- Add html_module.unescape() for title and description in plugin.py
- Add test fixture with special characters
- Add test verifying no double-encoded entities
---
 mkdocs_rss_plugin/plugin.py                   | 14 ++--
 .../fixtures/docs/page_with_special_chars.md  | 11 +++
 tests/test_double_encoded_entities.py         | 72 +++++++++++++++++++
 3 files changed, 92 insertions(+), 5 deletions(-)
 create mode 100644 tests/fixtures/docs/page_with_special_chars.md
 create mode 100644 tests/test_double_encoded_entities.py

diff --git a/mkdocs_rss_plugin/plugin.py b/mkdocs_rss_plugin/plugin.py
index a650280..95cefaf 100644
--- a/mkdocs_rss_plugin/plugin.py
+++ b/mkdocs_rss_plugin/plugin.py
@@ -5,6 +5,7 @@
 # ##################################
 
 # standard library
+import html as html_module
 import json
 from copy import deepcopy
 from dataclasses import asdict
@@ -350,14 +351,17 @@ def on_page_content(
                 ),
                 comments_url=page_url_comments,
                 created=page_dates[0],
-                description=self.util.get_description_or_abstract(
-                    in_page=page,
-                    chars_count=self.config.abstract_chars_count,
-                    abstract_delimiter=self.config.abstract_delimiter,
+                description=html_module.unescape(
+                    self.util.get_description_or_abstract(
+                        in_page=page,
+                        chars_count=self.config.abstract_chars_count,
+                        abstract_delimiter=self.config.abstract_delimiter,
+                    )
+                    or ""
                 ),
                 guid=page.canonical_url,
                 link=page_url_full,
-                title=page.title,
+                title=html_module.unescape(page.title) if page.title else None,
                 updated=page_dates[1],
                 # for later fetch
                 _mkdocs_page_ref=MkdocsPageSubset.from_page(page),
diff --git a/tests/fixtures/docs/page_with_special_chars.md b/tests/fixtures/docs/page_with_special_chars.md
new file mode 100644
index 0000000..ac9e248
--- /dev/null
+++ b/tests/fixtures/docs/page_with_special_chars.md
@@ -0,0 +1,11 @@
+---
+title: "Test: A & B <C> D"
+authors:
+    - Test Author
+date: 2024-01-15 10:00
+description: "Description with & ampersand and <angle> brackets"
+---
+
+# Test page with special characters
+
+This page tests that special characters are properly encoded in the RSS feed.
diff --git a/tests/test_double_encoded_entities.py b/tests/test_double_encoded_entities.py
new file mode 100644
index 0000000..f3cb3bb
--- /dev/null
+++ b/tests/test_double_encoded_entities.py
@@ -0,0 +1,72 @@
+#! python3  # noqa: E265
+
+"""Test that title and description don't contain double-encoded HTML entities.
+
+MkDocs pre-escapes content, so Jinja's |e filter should not double-encode.
+
+Usage from the repo root folder:
+
+    python -m unittest tests.test_double_encoded_entities
+
+"""
+
+# #############################################################################
+# ########## Libraries #############
+# ##################################
+
+# Standard library
+import logging
+import tempfile
+from pathlib import Path
+from traceback import format_exception
+
+# test suite
+from tests.base import BaseTest
+
+# -- Globals --
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+
+OUTPUT_RSS_FEED_CREATED = "feed_rss_created.xml"
+
+# #############################################################################
+# ########## Classes ###############
+# ##################################
+
+
+class TestDoubleEncodedEntities(BaseTest):
+    """Test that HTML entities are not double-encoded in RSS feed."""
+
+    def test_no_double_encoded_entities(self):
+        """Verify that title and description don't contain double-encoded HTML entities.
+
+        MkDocs pre-escapes content, so Jinja's |e filter should not double-encode.
+        """
+        with tempfile.TemporaryDirectory() as tmpdirname:
+            cli_result = self.build_docs_setup(
+                testproject_path="docs",
+                mkdocs_yml_filepath=Path("tests/fixtures/mkdocs_complete.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)
+
+            # Read raw XML content
+            rss_path = Path(tmpdirname) / OUTPUT_RSS_FEED_CREATED
+            rss_content = rss_path.read_text()
+
+            # Check for double-encoded entities
+            double_encoded = ["&amp;amp;", "&amp;lt;", "&amp;gt;"]
+            for entity in double_encoded:
+                self.assertNotIn(
+                    entity,
+                    rss_content,
+                    f"Found double-encoded HTML entity {entity} in RSS feed. "
+                    "This indicates MkDocs pre-escaping combined with Jinja |e filter.",
+                )