Skip to content

Commit bf40242

Browse files
awanlinawanlin
authored
Merge pull request #247 from DSmedley/main
Add support for optional PyMdown blocks extension syntax
2 parents f262e46 + 324985e commit bf40242

4 files changed

Lines changed: 128 additions & 20 deletions

File tree

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,14 @@ plugins:
3333
use_material_search: true
3434
```
3535

36+
(Optional) To use [PyMdown Blocks Extensions](https://facelessuser.github.io/pymdown-extensions/extensions/blocks/) (replaces `admonitions`, `pymdownx.details` and `pymdownx.tabbed` extensions), you need to add the following configuration to your `mkdocs.yml`:
37+
38+
```yaml
39+
plugins:
40+
- techdocs-core:
41+
use_pymdownx_blocks: true
42+
```
43+
3644
## Development
3745

3846
### Running Locally
@@ -149,6 +157,10 @@ We only use `material-mkdocs` as base styles because Backstage also uses the `Ma
149157

150158
## Changelog
151159

160+
### 1.5.3
161+
162+
- Added support for PyMdown Blocks extensions
163+
152164
### 1.5.2
153165

154166
- Update `markdown_inline_graphviz_extension` to use forked `markdown-graphviz-inline` instead due to abandonment of original dependency.

‎setup.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828

2929
setup(
3030
name="mkdocs-techdocs-core",
31-
version="1.5.2",
31+
version="1.5.3",
3232
description="The core MkDocs plugin used by Backstage's TechDocs as a wrapper around "
3333
"multiple MkDocs plugins and Python Markdown extensions",
3434
long_description=long_description,

‎techdocs_core/core.py‎

Lines changed: 67 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
"""
2-
* Copyright 2020 The Backstage Authors
3-
*
4-
* Licensed under the Apache License, Version 2.0 (the "License");
5-
* you may not use this file except in compliance with the License.
6-
* You may obtain a copy of the License at
7-
*
8-
* http://www.apache.org/licenses/LICENSE-2.0
9-
*
10-
* Unless required by applicable law or agreed to in writing, software
11-
* distributed under the License is distributed on an "AS IS" BASIS,
12-
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13-
* See the License for the specific language governing permissions and
14-
* limitations under the License.
2+
* Copyright 2020 The Backstage Authors
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
1515
"""
1616

1717
import tempfile
@@ -79,6 +79,9 @@ def on_config(self, config):
7979
use_material_search = config["plugins"]["techdocs-core"].config.get(
8080
"use_material_search", False
8181
)
82+
use_pymdownx_blocks = config["plugins"]["techdocs-core"].config.get(
83+
"use_pymdownx_blocks", False
84+
)
8285
del config["plugins"]["techdocs-core"]
8386

8487
if use_material_search:
@@ -99,15 +102,64 @@ def on_config(self, config):
99102
if "mdx_configs" not in config:
100103
config["mdx_configs"] = {}
101104

102-
config["markdown_extensions"].append("admonition")
103105
config["markdown_extensions"].append("toc")
104106
config["mdx_configs"]["toc"] = {
105107
"permalink": True,
106108
}
107109

110+
if use_pymdownx_blocks:
111+
config["markdown_extensions"].append("pymdownx.blocks.admonition")
112+
config["mdx_configs"]["pymdownx.blocks.admonition"] = {
113+
"types": [
114+
"new",
115+
"settings",
116+
"note",
117+
"abstract",
118+
"info",
119+
"tip",
120+
"success",
121+
"question",
122+
"warning",
123+
"failure",
124+
"danger",
125+
"bug",
126+
"example",
127+
"quote",
128+
]
129+
}
130+
config["markdown_extensions"].append("pymdownx.blocks.details")
131+
config["mdx_configs"]["pymdownx.blocks.details"] = {
132+
"types": [
133+
{"name": "details-new", "class": "new"},
134+
{"name": "details-settings", "class": "settings"},
135+
{"name": "details-note", "class": "note"},
136+
{"name": "details-abstract", "class": "abstract"},
137+
{"name": "details-info", "class": "info"},
138+
{"name": "details-tip", "class": "tip"},
139+
{"name": "details-success", "class": "success"},
140+
{"name": "details-question", "class": "question"},
141+
{"name": "details-warning", "class": "warning"},
142+
{"name": "details-failure", "class": "failure"},
143+
{"name": "details-danger", "class": "danger"},
144+
{"name": "details-bug", "class": "bug"},
145+
{"name": "details-example", "class": "example"},
146+
{"name": "details-quote", "class": "quote"},
147+
]
148+
}
149+
config["markdown_extensions"].append("pymdownx.blocks.tab")
150+
config["mdx_configs"]["pymdownx.blocks.tab"] = {
151+
"alternate_style": True,
152+
}
153+
else:
154+
config["markdown_extensions"].append("admonition")
155+
config["markdown_extensions"].append("pymdownx.details")
156+
config["markdown_extensions"].append("pymdownx.tabbed")
157+
config["mdx_configs"]["pymdownx.tabbed"] = {
158+
"alternate_style": True,
159+
}
160+
108161
config["markdown_extensions"].append("pymdownx.caret")
109162
config["markdown_extensions"].append("pymdownx.critic")
110-
config["markdown_extensions"].append("pymdownx.details")
111163
config["markdown_extensions"].append("pymdownx.emoji")
112164
config["mdx_configs"]["pymdownx.emoji"] = {"emoji_generator": to_svg}
113165
config["markdown_extensions"].append("pymdownx.inlinehilite")
@@ -124,10 +176,6 @@ def on_config(self, config):
124176
config["mdx_configs"]["pymdownx.betterem"] = {
125177
"smart_enable": "all",
126178
}
127-
config["markdown_extensions"].append("pymdownx.tabbed")
128-
config["mdx_configs"]["pymdownx.tabbed"] = {
129-
"alternate_style": True,
130-
}
131179
config["markdown_extensions"].append("pymdownx.tasklist")
132180
config["mdx_configs"]["pymdownx.tasklist"] = {
133181
"custom_checkbox": True,

‎techdocs_core/test_core.py‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,3 +131,51 @@ def test_default_search(self):
131131
self.assertEqual(
132132
final_config["plugins"]["search"].__module__, "mkdocs.contrib.search"
133133
)
134+
135+
def test_pymdownx_blocks(self):
136+
self.plugin_collection["techdocs-core"].load_config(
137+
{"use_pymdownx_blocks": True}
138+
)
139+
final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
140+
141+
self.assertTrue(
142+
"pymdownx.blocks.admonition" in final_config["markdown_extensions"]
143+
)
144+
self.assertTrue(
145+
"pymdownx.blocks.details" in final_config["markdown_extensions"]
146+
)
147+
self.assertTrue("pymdownx.blocks.tab" in final_config["markdown_extensions"])
148+
self.assertTrue(
149+
"types" in final_config["mdx_configs"]["pymdownx.blocks.admonition"]
150+
)
151+
self.assertTrue(
152+
"types" in final_config["mdx_configs"]["pymdownx.blocks.details"]
153+
)
154+
self.assertTrue(
155+
"alternate_style" in final_config["mdx_configs"]["pymdownx.blocks.tab"]
156+
)
157+
self.assertFalse("admonition" in final_config["markdown_extensions"])
158+
self.assertFalse("pymdownx.details" in final_config["markdown_extensions"])
159+
self.assertFalse("pymdownx.tabbed" in final_config["markdown_extensions"])
160+
self.assertFalse("pymdownx.tabbed" in final_config["mdx_configs"])
161+
162+
def test_default_pymdownx(self):
163+
self.plugin_collection["techdocs-core"].load_config({})
164+
final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
165+
166+
self.assertFalse(
167+
"pymdownx.blocks.admonition" in final_config["markdown_extensions"]
168+
)
169+
self.assertFalse(
170+
"pymdownx.blocks.details" in final_config["markdown_extensions"]
171+
)
172+
self.assertFalse("pymdownx.blocks.tab" in final_config["markdown_extensions"])
173+
self.assertFalse("pymdownx.blocks.admonition" in final_config["mdx_configs"])
174+
self.assertFalse("pymdownx.blocks.details" in final_config["mdx_configs"])
175+
self.assertFalse("pymdownx.blocks.tab" in final_config["mdx_configs"])
176+
self.assertTrue("admonition" in final_config["markdown_extensions"])
177+
self.assertTrue("pymdownx.details" in final_config["markdown_extensions"])
178+
self.assertTrue("pymdownx.tabbed" in final_config["markdown_extensions"])
179+
self.assertTrue(
180+
"alternate_style" in final_config["mdx_configs"]["pymdownx.tabbed"]
181+
)

0 commit comments

Comments
 (0)