Add support for optional PyMdown blocks extension syntax

Author: DSmedley

README.md

@@ -33,6 +33,14 @@ plugins:
       use_material_search: true
 ```
 
+(Optional) To use [PyMdown Blocks Extensions](https://facelessuser.github.io/pymdown-extensions/extensions/blocks/api/) (replaces `admonitions`, `pymdownx.details` and `pymdownx.tabbed` extensions), you need to add the following configuration to your `mkdocs.yml`:
+
+```yaml
+plugins:
+  - techdocs-core:
+      use_pymdownx_blocks: true
+```
+
 ## Development
 
 ### Running Locally
@@ -149,6 +157,10 @@ We only use `material-mkdocs` as base styles because Backstage also uses the `Ma
 
 ## Changelog
 
+### 1.5.3
+
+- Added support for PyMdown Blocks extensions
+
 ### 1.5.2
 
 - Update `markdown_inline_graphviz_extension` to use forked `markdown-graphviz-inline` instead due to abandonment of original dependency.

techdocs_core/core.py

@@ -79,6 +79,9 @@ def on_config(self, config):
         use_material_search = config["plugins"]["techdocs-core"].config.get(
             "use_material_search", False
         )
+        use_pymdownx_blocks = config["plugins"]["techdocs-core"].config.get(
+            "use_pymdownx_blocks", False
+        )
         del config["plugins"]["techdocs-core"]
 
         if use_material_search:
@@ -99,15 +102,64 @@ def on_config(self, config):
         if "mdx_configs" not in config:
             config["mdx_configs"] = {}
 
-        config["markdown_extensions"].append("admonition")
         config["markdown_extensions"].append("toc")
         config["mdx_configs"]["toc"] = {
             "permalink": True,
         }
 
+        if use_pymdownx_blocks:
+            config["markdown_extensions"].append("pymdownx.blocks.admonition")
+            config["mdx_configs"]["pymdownx.blocks.admonition"] = {
+                "types": [
+                    "new",
+                    "settings",
+                    "note",
+                    "abstract",
+                    "info",
+                    "tip",
+                    "success",
+                    "question",
+                    "warning",
+                    "failure",
+                    "danger",
+                    "bug",
+                    "example",
+                    "quote"
+                ]
+            }
+            config["markdown_extensions"].append("pymdownx.blocks.details")
+            config["mdx_configs"]["pymdownx.blocks.details"] = {
+                "types": [
+                    {"name": "details-new", "class": "new"},
+                    {"name": "details-settings", "class": "settings"},
+                    {"name": "details-note", "class": "note"},
+                    {"name": "details-abstract", "class": "abstract"},
+                    {"name": "details-info", "class": "info"},
+                    {"name": "details-tip", "class": "tip"},
+                    {"name": "details-success", "class": "success"},
+                    {"name": "details-question", "class": "question"},
+                    {"name": "details-warning", "class": "warning"},
+                    {"name": "details-failure", "class": "failure"},
+                    {"name": "details-danger", "class": "danger"},
+                    {"name": "details-bug", "class": "bug"},
+                    {"name": "details-example", "class": "example"},
+                    {"name": "details-quote", "class": "quote"}
+                ]
+            }
+            config["markdown_extensions"].append("pymdownx.blocks.tab")
+            config["mdx_configs"]["pymdownx.blocks.tab"] = {
+                "alternate_style": True,
+            }
+        else:
+            config["markdown_extensions"].append("admonition")
+            config["markdown_extensions"].append("pymdownx.details")
+            config["markdown_extensions"].append("pymdownx.tabbed")
+            config["mdx_configs"]["pymdownx.tabbed"] = {
+                "alternate_style": True,
+            }
+
         config["markdown_extensions"].append("pymdownx.caret")
         config["markdown_extensions"].append("pymdownx.critic")
-        config["markdown_extensions"].append("pymdownx.details")
         config["markdown_extensions"].append("pymdownx.emoji")
         config["mdx_configs"]["pymdownx.emoji"] = {"emoji_generator": to_svg}
         config["markdown_extensions"].append("pymdownx.inlinehilite")
@@ -124,10 +176,6 @@ def on_config(self, config):
         config["mdx_configs"]["pymdownx.betterem"] = {
             "smart_enable": "all",
         }
-        config["markdown_extensions"].append("pymdownx.tabbed")
-        config["mdx_configs"]["pymdownx.tabbed"] = {
-            "alternate_style": True,
-        }
         config["markdown_extensions"].append("pymdownx.tasklist")
         config["mdx_configs"]["pymdownx.tasklist"] = {
             "custom_checkbox": True,

techdocs_core/test_core.py

@@ -131,3 +131,35 @@ def test_default_search(self):
         self.assertEqual(
             final_config["plugins"]["search"].__module__, "mkdocs.contrib.search"
         )
+
+    def test_pymdownx_blocks(self):
+        self.plugin_collection["techdocs-core"].load_config(
+            {"use_pymdownx_blocks": True}
+        )
+        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+
+        self.assertTrue("pymdownx.blocks.admonition" in final_config["markdown_extensions"])
+        self.assertTrue("pymdownx.blocks.details" in final_config["markdown_extensions"])
+        self.assertTrue("pymdownx.blocks.tab" in final_config["markdown_extensions"])
+        self.assertTrue("types" in final_config["mdx_configs"]["pymdownx.blocks.admonition"])
+        self.assertTrue("types" in final_config["mdx_configs"]["pymdownx.blocks.details"])
+        self.assertTrue("alternate_style" in final_config["mdx_configs"]["pymdownx.blocks.tab"])
+        self.assertFalse("admonition" in final_config["markdown_extensions"])
+        self.assertFalse("pymdownx.details" in final_config["markdown_extensions"])
+        self.assertFalse("pymdownx.tabbed" in final_config["markdown_extensions"])
+        self.assertFalse("pymdownx.tabbed" in final_config["mdx_configs"])
+
+    def test_default_pymdownx(self):
+        self.plugin_collection["techdocs-core"].load_config({})
+        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+
+        self.assertFalse("pymdownx.blocks.admonition" in final_config["markdown_extensions"])
+        self.assertFalse("pymdownx.blocks.details" in final_config["markdown_extensions"])
+        self.assertFalse("pymdownx.blocks.tab" in final_config["markdown_extensions"])
+        self.assertFalse("pymdownx.blocks.admonition" in final_config["mdx_configs"])
+        self.assertFalse("pymdownx.blocks.details" in final_config["mdx_configs"])
+        self.assertFalse("pymdownx.blocks.tab" in final_config["mdx_configs"])
+        self.assertTrue("admonition" in final_config["markdown_extensions"])
+        self.assertTrue("pymdownx.details" in final_config["markdown_extensions"])
+        self.assertTrue("pymdownx.tabbed" in final_config["markdown_extensions"])
+        self.assertTrue("alternate_style" in final_config["mdx_configs"]["pymdownx.tabbed"])