add(integrations): support integrations with MaterialX theme, fork of Material for Mkdocs (#437)

FYI @jaywhj

Author: Guts

docs/integrations.md

@@ -3,6 +3,8 @@ title: Integrations
 icon: octicons/plug-16
 ---
 
+Since version 1.19, the plugin supports both [Material for Mkdocs](https://squidfunk.github.io/mkdocs-material/) (which is in maintenance mode since Nov 11, 2025 and until November 2026) and its fork [MaterialX](https://jaywhj.github.io/mkdocs-materialx/).
+
 ## Blog plugin (from Material theme)
 
 Since version 1.17, the plugin integrates with the [Blog plugin (shipped with Material theme)](https://squidfunk.github.io/mkdocs-material/plugins/blog/) (see also [the tutorial about blog + RSS  plugins](https://squidfunk.github.io/mkdocs-material/tutorials/blogs/engage/)).

mkdocs_rss_plugin/integrations/theme_material_base.py

@@ -33,6 +33,7 @@
 class IntegrationMaterialThemeBase:
     # attributes
     IS_THEME_MATERIAL: bool = False
+    THEME_NAME: str = "mkdocs"
 
     def __init__(self, mkdocs_config: MkDocsConfig) -> None:
         """Integration instantiation.
@@ -54,10 +55,23 @@ def is_mkdocs_theme_material(
             mkdocs_config (Optional[MkDocsConfig]): Mkdocs website configuration object.
 
         Returns:
-            bool: True if the theme's name is 'material'. False if not.
+            bool: True if the theme's name is 'material' or 'materialx'. False if not.
         """
         if mkdocs_config is None and isinstance(self.mkdocs_config, MkDocsConfig):
             mkdocs_config: MkDocsConfig = self.mkdocs_config
 
-        self.IS_THEME_MATERIAL = mkdocs_config.theme.name == "material"
-        return self.IS_THEME_MATERIAL
+        if isinstance(mkdocs_config, MkDocsConfig):
+            self.THEME_NAME = (
+                mkdocs_config.theme.name if mkdocs_config.theme else "mkdocs"
+            )
+            self.IS_THEME_MATERIAL = mkdocs_config.theme.name in (
+                "material",
+                "materialx",
+            )
+            return self.IS_THEME_MATERIAL
+
+        logger.warning(
+            "Cannot check if the theme is Material or not because the MkDocs "
+            "configuration object is not available."
+        )
+        return False

mkdocs_rss_plugin/integrations/theme_material_blog_plugin.py

@@ -86,13 +86,13 @@ def is_blog_plugin_enabled_mkdocs(self, mkdocs_config: MkDocsConfig | None) -> b
             logger.debug("Installed theme is not 'material'. Integration disabled.")
             return False
 
-        if mkdocs_config.plugins.get("material/blog") is None:
+        if mkdocs_config.plugins.get(f"{self.THEME_NAME}/blog") is None:
             logger.debug("Material blog plugin is not listed in configuration.")
             self.IS_BLOG_PLUGIN_ENABLED = False
             return False
 
         self.blog_plugin_cfg: BlogPlugin | None = mkdocs_config.plugins.get(
-            "material/blog"
+            f"{self.THEME_NAME}/blog"
         )
 
         if not self.blog_plugin_cfg.config.enabled:

mkdocs_rss_plugin/integrations/theme_material_social_plugin.py

@@ -118,11 +118,11 @@ def is_social_plugin_enabled_mkdocs(
             logger.debug("Installed theme is not 'material'. Integration disabled.")
             return False
 
-        if not mkdocs_config.plugins.get("material/social"):
+        if not mkdocs_config.plugins.get(f"{self.THEME_NAME}/social"):
             logger.debug("Material Social plugin not listed in configuration.")
             return False
 
-        social_plugin_cfg = mkdocs_config.plugins.get("material/social")
+        social_plugin_cfg = mkdocs_config.plugins.get(f"{self.THEME_NAME}/social")
 
         if not social_plugin_cfg.config.enabled:
             logger.debug("Material Social plugin is installed but disabled.")
@@ -147,7 +147,7 @@ def is_social_plugin_and_cards_enabled_mkdocs(
         if not self.is_social_plugin_enabled_mkdocs(mkdocs_config=mkdocs_config):
             return False
 
-        social_plugin_cfg = mkdocs_config.plugins.get("material/social")
+        social_plugin_cfg = mkdocs_config.plugins.get(f"{self.THEME_NAME}/social")
 
         if not social_plugin_cfg.config.cards:
             logger.debug(
@@ -212,7 +212,7 @@ def get_social_cards_dir(self, mkdocs_config: MkDocsConfig) -> str:
         Returns:
             str: The cards_dir if the theme material and the plugin social cards is enabled.
         """
-        social_plugin_cfg = mkdocs_config.plugins.get("material/social")
+        social_plugin_cfg = mkdocs_config.plugins.get(f"{self.THEME_NAME}/social")
 
         logger.debug(
             "Material Social cards folder in Mkdocs build directory: "
@@ -246,7 +246,7 @@ def get_social_cards_cache_dir(self, mkdocs_config: MkDocsConfig) -> Path:
         Returns:
             Path: The cache dir if the theme material and the plugin social cards is enabled.
         """
-        social_plugin_cfg = mkdocs_config.plugins.get("material/social")
+        social_plugin_cfg = mkdocs_config.plugins.get(f"{self.THEME_NAME}/social")
 
         if (
             Path(social_plugin_cfg.config.cache_dir)

pyproject.toml

@@ -70,6 +70,7 @@ test = [
     "feedparser>=6.0.12,<6.1",
     "jsonfeed-util>=1.2,<2",
     "mkdocs-material[imaging]>=9.7,<9.8",
+    "mkdocs-materialx[imaging]>=10.1.3,<11",
     "pytest-cov>=6.9.1,<8",
     "validator-collection>=1.5,<1.6",
 ]

tests/fixtures/mkdocs_materialx_item_image_social_cards_blog.yml

@@ -0,0 +1,16 @@
+site_name: Test RSS Plugin
+site_description: Test social cards support in RSS with blog plugin also enabled
+site_url: https://guts.github.io/mkdocs-rss-plugin
+
+plugins:
+  - blog:
+      blog_dir: blog
+  - rss:
+      match_path: blog/posts/.*
+      pretty_print: true
+  - social:
+      enabled: true
+      cards: true
+
+theme:
+  name: materialx

tests/test_config.py

@@ -157,8 +157,8 @@ def test_plugin_config_image(self):
 
     def test_plugin_config_through_mkdocs(self):
         for config_filepath in self.config_files:
-            plg_cfg = self.get_plugin_config_from_mkdocs(config_filepath, "rss")
             print(config_filepath)
+            plg_cfg = self.get_plugin_config_from_mkdocs(config_filepath, "rss")
             self.assertIsInstance(plg_cfg, Config)
 
 

tests/test_integrations_material_social_cards.py

@@ -137,6 +137,27 @@ def test_plugin_config_social_cards_enabled_with_blog_plugin(self):
         )
         self.assertTrue(integration_social_cards.IS_ENABLED)
 
+    def test_plugin_config_materialx_social_cards_enabled_with_blog_plugin(self):
+        # default reference
+        cfg_mkdocs = load_config(
+            str(
+                Path(
+                    "tests/fixtures/mkdocs_materialx_item_image_social_cards_blog.yml"
+                ).resolve()
+            )
+        )
+
+        integration_social_cards = IntegrationMaterialSocialCards(
+            mkdocs_config=cfg_mkdocs
+        )
+        self.assertTrue(integration_social_cards.IS_THEME_MATERIAL)
+        self.assertTrue(integration_social_cards.IS_SOCIAL_PLUGIN_ENABLED)
+        self.assertTrue(integration_social_cards.IS_SOCIAL_PLUGIN_CARDS_ENABLED)
+        self.assertTrue(
+            integration_social_cards.integration_material_blog.IS_BLOG_PLUGIN_ENABLED
+        )
+        self.assertTrue(integration_social_cards.IS_ENABLED)
+
     def test_plugin_config_social_cards_enabled_with_directory_urls_disabled(self):
         """Test case described in https://github.com/Guts/mkdocs-rss-plugin/issues/319."""
         # default reference