0
# PyMdown Extensions
1
2
A comprehensive collection of extensions for Python Markdown that significantly enhances its functionality beyond the standard library. Provides 20+ specialized extensions covering syntax highlighting, mathematical expressions, enhanced emphasis formatting, code fencing with custom formatters, emoji support, task lists, tabbed content, progress bars, smart symbols, and advanced linking capabilities.
3
4
## Package Information
5
6
- **Package Name**: pymdown-extensions
7
- **Language**: Python
8
- **Installation**: `pip install pymdown-extensions`
9
- **Optional Dependencies**: `pip install pymdown-extensions[extra]` (includes Pygments for syntax highlighting)
10
11
## Core Imports
12
13
```python
14
import markdown
15
```
16
17
Typical usage pattern:
18
19
```python
20
import markdown
21
22
# Use extensions by name
23
md = markdown.Markdown(extensions=['pymdownx.betterem', 'pymdownx.superfences'])
24
```
25
26
Direct extension import:
27
28
```python
29
from pymdownx import betterem, superfences
30
31
# Create extension instances
32
md = markdown.Markdown(extensions=[
33
betterem.makeExtension(),
34
superfences.makeExtension()
35
])
36
```
37
38
## Basic Usage
39
40
```python
41
import markdown
42
43
# Basic markdown with pymdown extensions
44
md = markdown.Markdown(extensions=[
45
'pymdownx.betterem', # Better emphasis handling
46
'pymdownx.superfences', # Enhanced code blocks
47
'pymdownx.tasklist', # Task lists with checkboxes
48
'pymdownx.emoji', # Emoji support
49
'pymdownx.magiclink' # Auto-linking
50
])
51
52
# Convert markdown to HTML
53
text = """
54
# Example Document
55
56
This is **bold** and *italic* text.
57
58
- [x] Completed task
59
- [ ] Pending task
60
61
:smile: :heart: :+1:
62
63
https://github.com/facelessuser/pymdown-extensions
64
"""
65
66
html = md.convert(text)
67
print(html)
68
```
69
70
## Architecture
71
72
PyMdown Extensions follows the standard Python-Markdown extension pattern:
73
74
- **Extension Classes**: Each extension inherits from `markdown.Extension`
75
- **Processors**: Handle specific markdown patterns (preprocessors, inline processors, block processors, tree processors, postprocessors)
76
- **Factory Functions**: `makeExtension()` functions provide standard instantiation interface
77
- **Configuration**: Extensions accept configuration via standard markdown extension config pattern
78
- **Utility Framework**: Common utilities in `pymdownx.util` for extension development
79
80
The package provides a consistent API across all extensions while offering extensive customization options for each specific markdown enhancement.
81
82
## Capabilities
83
84
### Text Enhancement Extensions
85
86
Extensions that enhance text formatting including better emphasis handling, insert/delete markup, superscript/subscript, highlighting, and smart symbol replacement.
87
88
```python { .api }
89
# Better emphasis with configurable asterisk/underscore handling
90
def makeExtension(**kwargs): ... # pymdownx.betterem
91
92
# Insert tags and superscript using caret syntax
93
def makeExtension(**kwargs): ... # pymdownx.caret
94
95
# Delete strikethrough and subscript using tilde syntax
96
def makeExtension(**kwargs): ... # pymdownx.tilde
97
98
# Text highlighting using mark tags
99
def makeExtension(**kwargs): ... # pymdownx.mark
100
101
# Smart replacement of ASCII with Unicode symbols
102
def makeExtension(**kwargs): ... # pymdownx.smartsymbols
103
```
104
105
[Text Enhancement](./text-enhancement.md)
106
107
### Code and Math Extensions
108
109
Extensions for syntax highlighting, mathematical expressions, inline code highlighting, and enhanced fenced code blocks with custom formatters.
110
111
```python { .api }
112
# Advanced code syntax highlighting
113
def makeExtension(**kwargs): ... # pymdownx.highlight
114
115
# Inline code syntax highlighting
116
def makeExtension(**kwargs): ... # pymdownx.inlinehilite
117
118
# Enhanced fenced code blocks with custom formatters
119
def makeExtension(**kwargs): ... # pymdownx.superfences
120
121
# LaTeX math rendering support
122
def makeExtension(**kwargs): ... # pymdownx.arithmatex
123
124
# Base64 image embedding for offline documents
125
def makeExtension(**kwargs): ... # pymdownx.b64
126
```
127
128
[Code and Math](./code-and-math.md)
129
130
### Content Structure Extensions
131
132
Extensions for organizing content including task lists, tabbed interfaces, collapsible details, progress bars, and enhanced lists.
133
134
```python { .api }
135
# GitHub-style task lists with checkboxes
136
def makeExtension(**kwargs): ... # pymdownx.tasklist
137
138
# Tabbed content blocks and interfaces
139
def makeExtension(**kwargs): ... # pymdownx.tabbed
140
141
# HTML details/summary collapsible blocks
142
def makeExtension(**kwargs): ... # pymdownx.details
143
144
# Visual progress bars with percentage indicators
145
def makeExtension(**kwargs): ... # pymdownx.progressbar
146
147
# Enhanced ordered lists with custom numbering
148
def makeExtension(**kwargs): ... # pymdownx.fancylists
149
```
150
151
[Content Structure](./content-structure.md)
152
153
### Linking and Media Extensions
154
155
Extensions for automatic linking, emoji support, keyboard key formatting, and link processing enhancements.
156
157
```python { .api }
158
# Comprehensive emoji support with multiple providers
159
def makeExtension(**kwargs): ... # pymdownx.emoji
160
161
# Automatic linking for URLs, emails, repositories
162
def makeExtension(**kwargs): ... # pymdownx.magiclink
163
164
# Keyboard key styling and formatting
165
def makeExtension(**kwargs): ... # pymdownx.keys
166
167
# Convert and normalize file paths in links
168
def makeExtension(**kwargs): ... # pymdownx.pathconverter
169
```
170
171
[Linking and Media](./linking-and-media.md)
172
173
### Advanced Block Extensions
174
175
Extensions using the generic blocks framework for admonitions, captions, definitions, HTML blocks, and other structured content.
176
177
```python { .api }
178
# Generic block processing framework
179
def makeExtension(**kwargs): ... # pymdownx.blocks
180
181
# Individual block implementations
182
class Admonition: ... # pymdownx.blocks.admonition
183
class Details: ... # pymdownx.blocks.details
184
class Tab: ... # pymdownx.blocks.tab
185
class Caption: ... # pymdownx.blocks.caption
186
class Definition: ... # pymdownx.blocks.definition
187
class HTML: ... # pymdownx.blocks.html
188
```
189
190
[Advanced Blocks](./advanced-blocks.md)
191
192
### Utility and Specialized Extensions
193
194
Utility extensions, content processing tools, and specialized functionality including snippet inclusion, HTML processing, and development utilities.
195
196
```python { .api }
197
# Include external file content and code snippets
198
def makeExtension(**kwargs): ... # pymdownx.snippets
199
200
# Remove or escape HTML tags
201
def makeExtension(**kwargs): ... # pymdownx.striphtml
202
203
# Escape any character with backslash
204
def makeExtension(**kwargs): ... # pymdownx.escapeall
205
206
# CriticMarkup support for tracked changes
207
def makeExtension(**kwargs): ... # pymdownx.critic
208
209
# Enhanced version of Python-Markdown Extra
210
def makeExtension(**kwargs): ... # pymdownx.extra
211
```
212
213
[Utilities and Specialized](./utilities-specialized.md)
214
215
## Extension Configuration Pattern
216
217
All PyMdown Extensions follow the standard Python-Markdown configuration pattern:
218
219
```python { .api }
220
def makeExtension(*args, **kwargs):
221
"""
222
Standard extension factory function.
223
224
Parameters:
225
- *args: Positional arguments (usually config tuples)
226
- **kwargs: Configuration options as keyword arguments
227
228
Returns:
229
Extension instance configured with provided options
230
"""
231
```
232
233
## Common Utilities
234
235
```python { .api }
236
# Common utilities for extension development
237
class PatternSequenceProcessor: ...
238
def clamp(value, min_val, max_val): ...
239
def escape_chars(md, chars): ...
240
def deprecated(message): ...
241
```
242
243
## Types
244
245
```python { .api }
246
# Standard Python-Markdown types
247
from markdown import Extension, Preprocessor, InlineProcessor, BlockProcessor, Treeprocessor, Postprocessor
248
249
# Extension configuration
250
ConfigOption = Any # Configuration option value
251
ExtensionConfig = Dict[str, ConfigOption] # Extension configuration dictionary
252
```