feature: achieve social cards integration

mkdocs.yml

@@ -100,11 +100,14 @@ plugins:
         utm_source: "documentation"
         utm_medium: "RSS"
         utm_campaign: "feed-syndication"
+      use_git: true
+      use_material_social_cards: true
   - search:
       lang: en
   - social:
       enabled: !ENV [MKDOCS_ENABLE_PLUGIN_SOCIAL, true]
       cache_dir: !ENV [MKDOCS_PLUGIN_SOCIAL_CACHE_DIR, .cache/plugins/social]
+      cards: true
   - termynal:
       prompt_literal_start:
         - "$"

mkdocs_rss_plugin/integrations/theme_material_social_plugin.py

@@ -6,6 +6,7 @@
 
 # standard library
 import logging
+from pathlib import Path
 
 # 3rd party
 from mkdocs.config.config_options import Config
@@ -22,79 +23,193 @@
 # ################################
 
 
-def is_theme_material(mkdocs_config: Config) -> bool:
-    """Check if the theme set in mkdocs.yml is material or not.
+class IntegrationMaterialSocialCards:
+    # attributes
+    IS_ENABLED: bool = True
+    IS_SOCIAL_PLUGIN_ENABLED: bool = True
+    IS_SOCIAL_PLUGIN_CARDS_ENABLED: bool = True
+    IS_THEME_MATERIAL: bool = False
+
+    def __init__(self, mkdocs_config: Config, switch_force: bool = True) -> None:
+        """Integration instanciation.
+
+        Args:
+            mkdocs_config (Config): Mkdocs website configuration object.
+            switch_force (bool, optional): option to force integration disabling. Set
+                it to False to disable it even if Social Cards are enabled in Mkdocs
+                configuration. Defaults to True.
+        """
+        # check if the integration can be enabled or not
+        self.IS_SOCIAL_PLUGIN_CARDS_ENABLED = (
+            self.is_social_plugin_and_cards_enabled_mkdocs(mkdocs_config=mkdocs_config)
+        )
 
-    Args:
-        mkdocs_config (Config): Mkdocs website configuration object.
+        # if every conditions are True, enable the integration
+        self.IS_ENABLED = all(
+            [
+                self.IS_THEME_MATERIAL,
+                self.IS_SOCIAL_PLUGIN_ENABLED,
+                self.IS_SOCIAL_PLUGIN_CARDS_ENABLED,
+            ]
+        )
 
-    Returns:
-        bool: True if the theme's name is 'material'. False if not.
-    """
-    return mkdocs_config.theme.name == "material"
+        # except if the end-user wants to disable it
+        if switch_force is False:
+            self.IS_ENABLED = False
+            logger.debug(
+                "[rss-plugin] Integration with Social Cards (Material theme) is "
+                "disabled in plugin's option in Mkdocs configuration."
+            )
+
+        # if enabled, save some config elements
+        if self.IS_ENABLED:
+            self.mkdocs_site_url = mkdocs_config.site_url
+            self.mkdocs_site_build_dir = mkdocs_config.site_dir
+            self.social_cards_assets_dir = self.get_social_cards_dir(
+                mkdocs_config=mkdocs_config
+            )
+
+    def is_theme_material(self, mkdocs_config: Config) -> bool:
+        """Check if the theme set in mkdocs.yml is material or not.
+
+        Args:
+            mkdocs_config (Config): Mkdocs website configuration object.
+
+        Returns:
+            bool: True if the theme's name is 'material'. False if not.
+        """
+        self.IS_THEME_MATERIAL = mkdocs_config.theme.name == "material"
+        return self.IS_THEME_MATERIAL
+
+    def is_social_plugin_enabled_mkdocs(self, mkdocs_config: Config) -> bool:
+        """Check if social plugin is installed and enabled.
+
+        Args:
+            mkdocs_config (Config): Mkdocs website configuration object.
+
+        Returns:
+            bool: True if the theme material and the plugin social cards is enabled.
+        """
+        if not self.is_theme_material(mkdocs_config=mkdocs_config):
+            logger.debug(
+                "[rss-plugin] Installed theme is not 'material'. Integration disabled."
+            )
+            return False
+
+        if not mkdocs_config.plugins.get("material/social"):
+            logger.debug("[rss-plugin] 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("[rss-plugin] Social plugin is installed but disabled.")
+            self.IS_SOCIAL_PLUGIN_ENABLED = False
+            return False
+
+        logger.debug("[rss-plugin] Social plugin is enabled in Mkdocs configuration.")
+        self.IS_SOCIAL_PLUGIN_CARDS_ENABLED = True
+        return True
 
+    def is_social_plugin_and_cards_enabled_mkdocs(self, mkdocs_config: Config) -> bool:
+        """Check if social cards plugin is enabled.
 
-def is_social_plugin_enabled_mkdocs(mkdocs_config: Config) -> bool:
-    """Check if social cards plugin is enabled.
+        Args:
+            mkdocs_config (Config): Mkdocs website configuration object.
 
-    Args:
-        mkdocs_config (Config): Mkdocs website configuration object.
+        Returns:
+            bool: True if the theme material and the plugin social cards is enabled.
+        """
+        if not self.is_social_plugin_enabled_mkdocs(mkdocs_config=mkdocs_config):
+            return False
 
-    Returns:
-        bool: True if the theme material and the plugin social cards is enabled.
-    """
-    if not is_theme_material(mkdocs_config=mkdocs_config):
-        logger.debug(
-            "[rss-plugin] Installed theme is not 'material'. Integration disabled."
-        )
-        return False
+        social_plugin_cfg = mkdocs_config.plugins.get("material/social")
 
-    if not mkdocs_config.plugins.get("material/social"):
-        logger.debug("[rss-plugin] Social plugin not listed in configuration.")
-        return False
+        if not social_plugin_cfg.config.cards:
+            logger.debug(
+                "[rss-plugin] Social plugin is installed, present but cards are disabled."
+            )
+            self.IS_SOCIAL_PLUGIN_CARDS_ENABLED = False
+            return False
 
-    social_plugin_cfg = mkdocs_config.plugins.get("material/social")
+        logger.debug("[rss-plugin] Social cards are enabled in Mkdocs configuration.")
+        self.IS_SOCIAL_PLUGIN_CARDS_ENABLED = True
+        return True
 
-    if not social_plugin_cfg.config.enabled or not social_plugin_cfg.config.cards:
-        logger.debug(
-            "[rss-plugin] Social plugin is installed, present but cards are disabled."
+    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.
+
+        Args:
+            mkdocs_page (Page): Mkdocs page object.
+            fallback_value (bool, optional): fallback value. It might be the
+                'plugins.social.cards.enabled' option in Mkdocs config. Defaults to True.
+
+        Returns:
+            bool: True if the social cards are enabled for a page.
+        """
+        return mkdocs_page.meta.get("social", {"cards": fallback_value}).get(
+            "cards", fallback_value
         )
-        return False
-
-    logger.debug("[rss-plugin] Social cards are enabled in Mkdocs configuration.")
-    return True
 
+    def get_social_cards_dir(self, mkdocs_config: Config) -> str:
+        """Get Social Cards folder within Mkdocs site_dir.
+        See: https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_dir
 
-def is_social_plugin_enabled_page(mkdocs_page: Page) -> bool:
-    """Check if the social plugin is enabled or disabled for a specific page. Plugin
-        has to enabled in Mkdocs configuration before.
+        Args:
+            mkdocs_config (Config): Mkdocs website configuration object.
 
-    Args:
-        mkdocs_page (Page): Mkdocs page object.
+        Returns:
+            str: True if the theme material and the plugin social cards is enabled.
+        """
+        social_plugin_cfg = mkdocs_config.plugins.get("material/social")
 
-    Returns:
-        bool: True if the social cards are enabled for a page.
-    """
-    if (
-        "social" in mkdocs_page.meta
-        and mkdocs_page.meta.get("social").get(
-            "cards", is_social_plugin_enabled_mkdocs()
+        logger.debug(
+            "[rss-plugin] Social cards folder in Mkdocs build directory: "
+            f"{social_plugin_cfg.config.cards_dir}."
         )
-        is True
-    ):
-        return True
 
-    return False
+        return social_plugin_cfg.config.cards_dir
+
+    def get_social_card_build_path_for_page(
+        self, mkdocs_page: Page, mkdocs_site_dir: str | None = None
+    ) -> Path:
+        """Get social card URL for a specific page in documentation.
 
+        Args:
+            mkdocs_page (Page): Mkdocs page object.
+            mkdocs_site_dir (str | None, optional): Mkdocs build site dir. If None, the
+                'class.mkdocs_site_build_dir' is used. is Defaults to None.
 
-def get_social_card_url_for_page(mkdocs_config: Config, mkdocs_page: Page) -> str:
-    """Get social card URL for a specific page in documentation.
+        Returns:
+            str: URL 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
 
-    Args:
-        mkdocs_config (Config): Mkdocs website configuration object.
-        mkdocs_page (Page): Mkdocs page object.
+        return Path(
+            f"{mkdocs_site_dir}/{self.social_cards_assets_dir}/"
+            f"{Path(mkdocs_page.file.src_uri).with_suffix('.png')}"
+        )
 
-    Returns:
-        str: URL to the image once published
-    """
-    return f"{mkdocs_config.site_url}assets/images/social{mkdocs_page.abs_url[:-1]}.png"
+    def get_social_card_url_for_page(
+        self,
+        mkdocs_page: Page,
+        mkdocs_site_url: str | None = None,
+    ) -> str:
+        """Get social card URL for a specific page in documentation.
+
+        Args:
+            mkdocs_page (Page): Mkdocs page object.
+            mkdocs_site_url (str | None, optional): Mkdocs site URL. If None, the
+                'class.mkdocs_site_url' is used. is Defaults to None.
+
+        Returns:
+            str: URL to the image once published
+        """
+        if mkdocs_site_url is None and self.mkdocs_site_url:
+            mkdocs_site_url = self.mkdocs_site_url
+
+        return f"{mkdocs_site_url}assets/images/social/{Path(mkdocs_page.file.src_uri).with_suffix('.png')}"

mkdocs_rss_plugin/plugin.py

@@ -31,7 +31,7 @@
     OUTPUT_FEED_UPDATED,
 )
 from mkdocs_rss_plugin.integrations.theme_material_social_plugin import (
-    is_social_plugin_enabled_mkdocs,
+    IntegrationMaterialSocialCards,
 )
 from mkdocs_rss_plugin.models import PageInformation
 from mkdocs_rss_plugin.util import Util
@@ -83,21 +83,15 @@ def on_config(self, config: config_options.Config) -> dict:
             return config
 
         # integrations - check if theme is Material and if social cards are enabled
-        if self.config.use_material_social_cards:
-            self.integration_material_social_cards_enabled = (
-                is_social_plugin_enabled_mkdocs(mkdocs_config=config)
-            )
-        else:
-            logger.debug(
-                "[rss-plugin] Integration with Social Cards (Material theme) is "
-                "disabled by option in Mkdocs configuration."
-            )
-            self.integration_material_social_cards_enabled = False
+        self.integration_material_social_cards = IntegrationMaterialSocialCards(
+            mkdocs_config=config,
+            switch_force=self.config.use_material_social_cards,
+        )
 
         # instanciate plugin tooling
         self.util = Util(
             use_git=self.config.use_git,
-            integration_material_social_cards=self.integration_material_social_cards_enabled,
+            integration_material_social_cards=self.integration_material_social_cards,
         )
 
         # check template dirs