feature(social_card): integrate with Material Social cache mechanism

Author: Guts

mkdocs_rss_plugin/integrations/theme_material_social_plugin.py

@@ -5,6 +5,8 @@
 # ##################################
 
 # standard library
+import json
+from hashlib import md5
 from pathlib import Path
 
 # 3rd party
@@ -39,6 +41,7 @@ class IntegrationMaterialSocialCards:
     IS_SOCIAL_PLUGIN_CARDS_ENABLED: bool = True
     IS_THEME_MATERIAL: bool = False
     IS_INSIDERS: bool = False
+    CARDS_MANIFEST: dict | None = None
 
     def __init__(self, mkdocs_config: MkDocsConfig, switch_force: bool = True) -> None:
         """Integration instanciation.
@@ -62,7 +65,6 @@ def __init__(self, mkdocs_config: MkDocsConfig, switch_force: bool = True) -> No
                 self.IS_SOCIAL_PLUGIN_CARDS_ENABLED,
             ]
         )
-        self.IS_INSIDERS = self.is_mkdocs_theme_material_insiders()
 
         # except if the end-user wants to disable it
         if switch_force is False:
@@ -82,6 +84,12 @@ def __init__(self, mkdocs_config: MkDocsConfig, switch_force: bool = True) -> No
             self.social_cards_cache_dir = self.get_social_cards_cache_dir(
                 mkdocs_config=mkdocs_config
             )
+            if self.is_mkdocs_theme_material_insiders():
+                self.load_cache_cards_manifest()
+
+            # store some attributes used to compute social card hash
+            self.site_name = mkdocs_config.site_name
+            self.site_description = mkdocs_config.site_description or ""
 
     def is_mkdocs_theme_material(self, mkdocs_config: MkDocsConfig) -> bool:
         """Check if the theme set in mkdocs.yml is material or not.
@@ -107,9 +115,11 @@ def is_mkdocs_theme_material_insiders(self) -> bool | 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
 
     def is_social_plugin_enabled_mkdocs(self, mkdocs_config: MkDocsConfig) -> bool:
@@ -126,17 +136,17 @@ def is_social_plugin_enabled_mkdocs(self, mkdocs_config: MkDocsConfig) -> bool:
             return False
 
         if not mkdocs_config.plugins.get("material/social"):
-            logger.debug("Social plugin not listed in configuration.")
+            logger.debug("Material Social plugin not listed in configuration.")
             return False
 
         social_plugin_cfg = mkdocs_config.plugins.get("material/social")
 
         if not social_plugin_cfg.config.enabled:
-            logger.debug("Social plugin is installed but disabled.")
+            logger.debug("Material Social plugin is installed but disabled.")
             self.IS_SOCIAL_PLUGIN_ENABLED = False
             return False
 
-        logger.debug("Social plugin is enabled in Mkdocs configuration.")
+        logger.debug("Material Social plugin is enabled in Mkdocs configuration.")
         self.IS_SOCIAL_PLUGIN_CARDS_ENABLED = True
         return True
 
@@ -157,19 +167,21 @@ def is_social_plugin_and_cards_enabled_mkdocs(
         social_plugin_cfg = mkdocs_config.plugins.get("material/social")
 
         if not social_plugin_cfg.config.cards:
-            logger.debug("Social plugin is installed, present but cards are disabled.")
+            logger.debug(
+                "Material Social plugin is installed, present but cards are disabled."
+            )
             self.IS_SOCIAL_PLUGIN_CARDS_ENABLED = False
             return False
 
-        logger.debug("Social cards are enabled in Mkdocs configuration.")
+        logger.debug("Material Social cards are enabled in Mkdocs configuration.")
         self.IS_SOCIAL_PLUGIN_CARDS_ENABLED = True
         return True
 
     def is_social_plugin_enabled_page(
         self, mkdocs_page: Page, fallback_value: bool = True
     ) -> bool:
         """Check if the social plugin is enabled or disabled for a specific page. Plugin
-            has to enabled in Mkdocs configuration before.
+            has to be enabled in Mkdocs configuration before.
 
         Args:
             mkdocs_page (Page): Mkdocs page object.
@@ -183,7 +195,31 @@ def is_social_plugin_enabled_page(
             "cards", fallback_value
         )
 
-    def get_social_cards_build_dir(self, mkdocs_config: MkDocsConfig) -> str:
+    def load_cache_cards_manifest(self) -> dict | None:
+        """Load social cards manifest if the file exists.
+
+        Returns:
+            dict | None: manifest as dict or None if the file does not exist
+        """
+        cache_cards_manifest = Path(self.social_cards_cache_dir).joinpath(
+            "manifest.json"
+        )
+        if not cache_cards_manifest.is_file():
+            logger.debug(
+                "Material Social Cards cache manifest file not found: "
+                f"{cache_cards_manifest}"
+            )
+            return None
+
+        with cache_cards_manifest.open(mode="r", encoding="UTF-8") as manifest:
+            self.CARDS_MANIFEST = json.load(manifest)
+        logger.debug(
+            f"Material Social Cards cache manifest loaded from {cache_cards_manifest}"
+        )
+
+        return self.CARDS_MANIFEST
+
+    def get_social_cards_build_dir(self, mkdocs_config: MkDocsConfig) -> Path:
         """Get Social Cards folder within Mkdocs site_dir.
         See: https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_dir
 
@@ -196,13 +232,13 @@ def get_social_cards_build_dir(self, mkdocs_config: MkDocsConfig) -> str:
         social_plugin_cfg = mkdocs_config.plugins.get("material/social")
 
         logger.debug(
-            "Social cards folder in Mkdocs build directory: "
+            "Material Social cards folder in Mkdocs build directory: "
             f"{social_plugin_cfg.config.cards_dir}."
         )
 
-        return social_plugin_cfg.config.cards_dir
+        return Path(social_plugin_cfg.config.cards_dir).resolve()
 
-    def get_social_cards_cache_dir(self, mkdocs_config: MkDocsConfig) -> str:
+    def get_social_cards_cache_dir(self, mkdocs_config: MkDocsConfig) -> Path:
         """Get Social Cards folder within Mkdocs site_dir.
         See: https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_dir
 
@@ -213,16 +249,17 @@ def get_social_cards_cache_dir(self, mkdocs_config: MkDocsConfig) -> str:
             str: True 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()
 
         logger.debug(
-            "Social cards cache folder: " f"{social_plugin_cfg.config.cache_dir}."
+            "Material Social cards cache folder: " f"{self.social_cards_cache_dir}."
         )
 
-        return social_plugin_cfg.config.cache_dir
+        return self.social_cards_cache_dir
 
     def get_social_card_build_path_for_page(
         self, mkdocs_page: Page, mkdocs_site_dir: str | None = None
-    ) -> Path:
+    ) -> Path | None:
         """Get social card path in Mkdocs build dir for a specific page.
 
         Args:
@@ -231,31 +268,80 @@ def get_social_card_build_path_for_page(
                 'class.mkdocs_site_build_dir' is used. is Defaults to None.
 
         Returns:
-            str: path to the image once published
+            Path: path to the image once published
         """
         if mkdocs_site_dir is None and self.mkdocs_site_build_dir:
             mkdocs_site_dir = self.mkdocs_site_build_dir
 
-        return Path(
+        expected_built_card_path = Path(
             f"{mkdocs_site_dir}/{self.social_cards_assets_dir}/"
             f"{Path(mkdocs_page.file.src_uri).with_suffix('.png')}"
         )
 
-    def get_social_card_cache_path_for_page(self, mkdocs_page: Page) -> Path:
+        if expected_built_card_path.is_file():
+            logger.debug(
+                f"Social card file found in cache folder: {expected_built_card_path}"
+            )
+            return expected_built_card_path
+        else:
+            logger.debug(f"Not found: {expected_built_card_path}")
+            return None
+
+    def get_social_card_cache_path_for_page(self, mkdocs_page: 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.
+
         Args:
             mkdocs_page (Page): Mkdocs page object.
-            social_plugin_cache_dir (Optional[str], optional): Mkdocs build site dir. If None, the
-                'class.mkdocs_site_build_dir' is used. is Defaults to None.
 
         Returns:
-            str: path to the image once published
+            Path: path to the image in local cache folder if it exists
         """
-        return Path(
-            f"{self.social_cards_assets_dir}/"
-            f"{Path(mkdocs_page.file.src_uri).with_suffix('.png')}"
-        )
+        if self.IS_INSIDERS:
+            expected_cached_card_path = self.social_cards_cache_dir.joinpath(
+                f"assets/images/social/{Path(mkdocs_page.file.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"Not found: {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")
+            )
+            expected_cached_card_path = self.social_cards_cache_dir.joinpath(
+                f"{page_hash.hexdigest()}.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"Not found: {expected_cached_card_path}")
+            return None
 
     def get_social_card_url_for_page(
         self,

mkdocs_rss_plugin/util.py

@@ -534,40 +534,41 @@ def get_image(self, in_page: Page, base_url: str) -> tuple[str, str, int] | None
                 f"{in_page.file.src_uri}"
             )
         elif (
-            self.social_cards.IS_ENABLED
+            isinstance(self.social_cards, IntegrationMaterialSocialCards)
+            and self.social_cards.IS_ENABLED
             and self.social_cards.IS_SOCIAL_PLUGIN_CARDS_ENABLED
             and self.social_cards.is_social_plugin_enabled_page(
                 mkdocs_page=in_page,
-                fallback_value=self.social_cards,
+                fallback_value=self.social_cards.IS_SOCIAL_PLUGIN_CARDS_ENABLED,
             )
         ):
-            img_local_path = self.social_cards.get_social_card_build_path_for_page(
-                mkdocs_page=in_page
-            )
+
             img_url = self.social_cards.get_social_card_url_for_page(
                 mkdocs_page=in_page
             )
-            logger.debug(
-                f"Image found ({img_url}) from social cards for page: "
-                f"{in_page.file.src_uri}. Using local image to get mime and length: "
-                f"{img_local_path}"
-            )
-
-            if img_local_path.is_file():
-                logger.debug("Local image already exists. Using it to get its length.")
-                img_length = img_local_path.stat().st_size
+            if img_local_cache_path := self.social_cards.get_social_card_cache_path_for_page(
+                mkdocs_page=in_page
+            ):
+                img_length = img_local_cache_path.stat().st_size
+                img_type = guess_type(url=img_local_cache_path, strict=False)[0]
+            elif img_local_build_path := self.social_cards.get_social_card_build_path_for_page(
+                mkdocs_page=in_page
+            ):
+                img_length = img_local_build_path.stat().st_size
+                img_type = guess_type(url=img_local_build_path, strict=False)[0]
             else:
                 logger.debug(
-                    f"Social card: {img_local_path} still not exists. Trying to "
+                    "Social card still not exists locally. Trying to "
                     f"retrieve length from remote image: {img_url}. "
                     "Note that would work only if the social card image has been "
                     "already published before the build."
                 )
                 img_length = self.get_remote_image_length(image_url=img_url)
+                img_type = guess_type(url=img_url, strict=False)[0]
 
             return (
                 img_url,
-                guess_type(url=img_local_path, strict=False)[0],
+                img_type,
                 img_length,
             )