update(chore): bump minimal version of Material for Mkdocs since 9.7.x is the last one (#405)

- since Material for Mkdocs turned into maintenance mode, all insiders
features are available, so this PR remove code related to split feature
between community/insiders editions
- fix #404 
- improve integrations with Material theme

Author: Guts

mkdocs_rss_plugin/integrations/theme_material_base.py

@@ -33,7 +33,6 @@
 class IntegrationMaterialThemeBase:
     # attributes
     IS_THEME_MATERIAL: bool = False
-    IS_INSIDERS: bool | None = False
 
     def __init__(self, mkdocs_config: MkDocsConfig) -> None:
         """Integration instantiation.
@@ -45,7 +44,6 @@ def __init__(self, mkdocs_config: MkDocsConfig) -> None:
         self.mkdocs_config = mkdocs_config
 
         self.IS_THEME_MATERIAL = self.is_mkdocs_theme_material()
-        self.IS_INSIDERS = self.is_mkdocs_theme_material_insiders()
 
     def is_mkdocs_theme_material(
         self, mkdocs_config: MkDocsConfig | None = None
@@ -63,22 +61,3 @@ def is_mkdocs_theme_material(
 
         self.IS_THEME_MATERIAL = mkdocs_config.theme.name == "material"
         return self.IS_THEME_MATERIAL
-
-    def is_mkdocs_theme_material_insiders(self) -> bool | None:
-        """Check if the material theme is community or insiders edition.
-
-        Returns:
-            bool: True if the theme is Insiders edition. False if community. None if
-                the Material theme is not installed.
-        """
-        if not self.IS_THEME_MATERIAL:
-            return None
-
-        if material_version is not None and "insiders" in material_version:
-            logger.debug("Material theme edition INSIDERS")
-            self.IS_INSIDERS = True
-            return True
-        else:
-            logger.debug("Material theme edition COMMUNITY")
-            self.IS_INSIDERS = False
-            return False

mkdocs_rss_plugin/integrations/theme_material_blog_plugin.py

@@ -11,18 +11,19 @@
 # 3rd party
 from mkdocs.config.defaults import MkDocsConfig
 from mkdocs.plugins import get_plugin_logger
-from mkdocs.structure.pages import Page
 
 # package
 from mkdocs_rss_plugin.constants import MKDOCS_LOGGER_NAME
 from mkdocs_rss_plugin.integrations.theme_material_base import (
     IntegrationMaterialThemeBase,
 )
+from mkdocs_rss_plugin.models import MkdocsPageSubset
 
 # conditional
 try:
     from material import __version__ as material_version
     from material.plugins.blog.plugin import BlogPlugin
+    from material.plugins.blog.structure import Post
 
 except ImportError:
     material_version = None
@@ -131,7 +132,7 @@ def author_name_from_id(self, author_id: str) -> str:
                 )
                 return author_id
 
-    def is_page_a_blog_post(self, mkdocs_page: Page) -> bool:
+    def is_page_a_blog_post(self, mkdocs_page: Post | MkdocsPageSubset) -> bool:
         """Identifies if the given page is part of Material Blog.
 
         Args:
@@ -140,6 +141,18 @@ def is_page_a_blog_post(self, mkdocs_page: Page) -> bool:
         Returns:
             bool: True if the given page is a Material Blog post.
         """
-        return Path(mkdocs_page.file.src_uri).is_relative_to(
-            self.blog_plugin_cfg.config.blog_dir
-        )
+        if self.IS_ENABLED and isinstance(mkdocs_page, Post):
+            logger.info(
+                f"page '{mkdocs_page.file.src_uri}' identified as Material Blog post."
+            )
+            return True
+        elif isinstance(mkdocs_page, MkdocsPageSubset) and Path(
+            mkdocs_page.src_uri
+        ).is_relative_to(self.blog_plugin_cfg.config.blog_dir):
+            logger.info(
+                f"page '{mkdocs_page.src_uri}' identified as Material Blog post "
+                f"by src_uri matching."
+            )
+            return True
+        else:
+            return False

mkdocs_rss_plugin/integrations/theme_material_social_plugin.py

@@ -6,7 +6,6 @@
 
 # standard library
 import json
-from hashlib import md5
 from pathlib import Path
 
 # 3rd party
@@ -98,8 +97,7 @@ def __init__(self, mkdocs_config: MkDocsConfig, switch_force: bool = True) -> No
                 mkdocs_config=mkdocs_config
             )
 
-            if self.is_mkdocs_theme_material_insiders():
-                self.load_cache_cards_manifest()
+            self.load_cache_cards_manifest()
 
             # store some attributes used to compute social card hash
             self.site_name = mkdocs_config.site_name
@@ -252,10 +250,26 @@ def get_social_cards_cache_dir(self, mkdocs_config: MkDocsConfig) -> Path:
             Path: The cache dir if the theme material and the plugin social cards is enabled.
         """
         social_plugin_cfg = mkdocs_config.plugins.get("material/social")
-        self.social_cards_cache_dir = Path(social_plugin_cfg.config.cache_dir).resolve()
+
+        if (
+            Path(social_plugin_cfg.config.cache_dir)
+            .resolve()
+            .is_relative_to(Path(mkdocs_config.config_file_path).parent.resolve())
+        ):
+            self.social_cards_cache_dir = Path(
+                social_plugin_cfg.config.cache_dir
+            ).resolve()
+        else:
+            self.social_cards_cache_dir = (
+                Path(mkdocs_config.config_file_path)
+                .parent.resolve()
+                .joinpath(social_plugin_cfg.config.cache_dir)
+            )
 
         logger.debug(
-            "Material Social cards cache folder: " f"{self.social_cards_cache_dir}."
+            "Material Social cards cache folder: "
+            f"{self.social_cards_cache_dir}. "
+            f"Already exists: {self.social_cards_cache_dir.is_dir()}"
         )
 
         return self.social_cards_cache_dir
@@ -307,61 +321,27 @@ def get_social_card_cache_path_for_page(
     ) -> Path | None:
         """Get social card path in social plugin cache folder for a specific page.
 
-        Note:
-            As we write this code (June 2024), the cache mechanism in Insiders edition
-            has stores images directly with the corresponding Page's path and name and
-            keep a correspondance matrix with hashes in a manifest.json;
-            the cache mechanism in Community edition uses the hash as file names without
-            any exposed matching criteria.
+        The cache mechanism in stores images directly with the
+        corresponding Page's path and name and keep a correspondance matrix with hashes
+        in a manifest.json.
 
         Args:
             mkdocs_page: Mkdocs page object.
 
         Returns:
             path to the image in local cache folder if it exists
         """
-        if self.IS_INSIDERS:
-
-            # if page is a blog post
-            if (
-                self.integration_material_blog.IS_BLOG_PLUGIN_ENABLED
-                and self.integration_material_blog.is_page_a_blog_post(mkdocs_page)
-            ):
-                expected_cached_card_path = self.social_cards_cache_dir.joinpath(
-                    f"assets/images/social/{Path(mkdocs_page.dest_uri).parent}.png"
-                )
-            else:
-                expected_cached_card_path = self.social_cards_cache_dir.joinpath(
-                    f"assets/images/social/{Path(mkdocs_page.src_uri).with_suffix('.png')}"
-                )
-
-            if expected_cached_card_path.is_file():
-                logger.debug(
-                    f"Social card file found in cache folder: {expected_cached_card_path}"
-                )
-                return expected_cached_card_path
-            else:
-                logger.debug(
-                    f"Social card not found in cache folder: {expected_cached_card_path}"
-                )
-
-        else:
-            if "description" in mkdocs_page.meta:
-                description = mkdocs_page.meta["description"]
-            else:
-                description = self.site_description
-
-            page_hash = md5(
-                "".join(
-                    [
-                        self.site_name,
-                        str(mkdocs_page.meta.get("title", mkdocs_page.title)),
-                        description,
-                    ]
-                ).encode("utf-8")
+        # if page is a blog post
+        if (
+            self.integration_material_blog.IS_BLOG_PLUGIN_ENABLED
+            and self.integration_material_blog.is_page_a_blog_post(mkdocs_page)
+        ):
+            expected_cached_card_path = self.social_cards_cache_dir.joinpath(
+                f"assets/images/social/{Path(mkdocs_page.dest_uri).parent}.png"
             )
+        else:
             expected_cached_card_path = self.social_cards_cache_dir.joinpath(
-                f"{page_hash.hexdigest()}.png"
+                f"assets/images/social/{Path(mkdocs_page.src_uri).with_suffix('.png')}"
             )
 
         if expected_cached_card_path.is_file():
@@ -370,8 +350,9 @@ def get_social_card_cache_path_for_page(
             )
             return expected_cached_card_path
         else:
-            logger.debug(f"Not found: {expected_cached_card_path}")
-            return None
+            logger.debug(
+                f"Social card not found in cache folder: {expected_cached_card_path}"
+            )
 
     def get_social_card_url_for_page(
         self,

pyproject.toml

@@ -59,15 +59,15 @@ dev = [
 docs = [
     "mkdocs-git-committers-plugin-2>=2.4.1,<2.6",
     "mkdocs-git-revision-date-localized-plugin>=1.3,<1.6",
-    "mkdocs-material[imaging]>=9.5.47,<10",
+    "mkdocs-material[imaging]>=9.7,<9.8",
     "mkdocs-minify-plugin>=0.8,<0.9",
     "mkdocstrings-python>=1.16.2,<1.19",
     "termynal>=0.12.2,<0.14",
 ]
 test = [
     "feedparser>=6.0.12,<6.1",
     "jsonfeed-util>=1.2,<2",
-    "mkdocs-material[imaging]>=9.6.23",
+    "mkdocs-material[imaging]>=9.7,<9.8",
     "pytest-cov>=6.9.1,<8",
     "validator-collection>=1.5,<1.6",
 ]