0
# Code and Math Extensions
1

2
Extensions for advanced code syntax highlighting, mathematical expressions, inline code highlighting, enhanced fenced code blocks with custom formatters, and multimedia content processing.
3

4
## Capabilities
5

6
### Highlight (Code Syntax Highlighting)
7

8
Advanced syntax highlighting for code blocks using Pygments, providing comprehensive language support and customizable formatting options.
9

10
```python { .api }
11
def makeExtension(**kwargs):
12
    """
13
    Create Highlight extension for code syntax highlighting.
14
    
15
    Configuration:
16
    - use_pygments: bool - Use Pygments for highlighting (True)
17
    - css_class: str - CSS class for highlighted code ('highlight')
18
    - pygments_style: str - Pygments style name ('default')
19
    - noclasses: bool - Inline styles instead of CSS classes (False)
20
    - linenums: bool - Enable line numbers (None)
21
    - linenums_style: str - Line number style ('table')
22
    - extend_pygments_lang: list - Additional language mappings
23
    
24
    Returns:
25
    HighlightExtension instance
26
    """
27

28
class HighlightExtension(Extension):
29
    """Advanced code highlighting extension."""
30

31
class Highlight:
32
    """Core highlighting class with Pygments integration."""
33

34
class HighlightTreeprocessor(Treeprocessor):
35
    """Processes code blocks for highlighting."""
36

37
class InlineHtmlFormatter:
38
    """Inline code formatter (requires Pygments)."""
39

40
class BlockHtmlFormatter:
41
    """Block code formatter (requires Pygments)."""
42
```
43

44
**Usage Example:**
45

46
```python
47
import markdown
48

49
# Basic usage with Pygments
50
md = markdown.Markdown(extensions=['pymdownx.highlight'])
51

52
# With custom configuration
53
md = markdown.Markdown(extensions=[
54
    'pymdownx.highlight'
55
], extension_configs={
56
    'pymdownx.highlight': {
57
        'pygments_style': 'github',
58
        'linenums': True,
59
        'linenums_style': 'pymdownx-inline'
60
    }
61
})
62

63
text = '''
64
```python
65
def hello_world():
66
    print("Hello, World!")
67
```
68
'''
69
html = md.convert(text)
70
```
71
72
### Inline Hilite (Inline Code Highlighting)
73

74
Syntax highlighting for inline code snippets, enabling language-specific highlighting within regular text.
75

76
```python { .api }
77
def makeExtension(**kwargs):
78
    """
79
    Create InlineHilite extension for inline code highlighting.
80
    
81
    Configuration:
82
    - css_class: str - CSS class for highlighted inline code ('highlight')
83
    - style_plain_text: bool - Style plain text inline code (True)
84
    - use_pygments: bool - Use Pygments for highlighting (True)
85
    
86
    Returns:
87
    InlineHiliteExtension instance
88
    """
89

90
class InlineHiliteExtension(Extension):
91
    """Inline code highlighting extension."""
92

93
class InlineHilitePattern(InlineProcessor):
94
    """Inline code pattern processor."""
95

96
class InlineHiliteException(Exception):
97
    """Custom exception for inline highlighting errors."""
98
```
99

100
**Usage Example:**
101

102
```python
103
import markdown
104

105
md = markdown.Markdown(extensions=['pymdownx.inlinehilite'])
106

107
# Inline code with language: `#!python print("Hello")`
108
text = "Use `#!python print('Hello World')` for output."
109
html = md.convert(text)
110
```
111

112
### SuperFences (Enhanced Fenced Code Blocks)
113

114
Advanced fenced code blocks with support for custom formatters, nested fences, and enhanced code block processing capabilities.
115

116
```python { .api }
117
def makeExtension(**kwargs):
118
    """
119
    Create SuperFences extension for enhanced code blocks.
120
    
121
    Configuration:
122
    - css_class: str - CSS class for code blocks ('highlight')
123
    - custom_fences: list - Custom fence configurations
124
    - disable_indented_code_blocks: bool - Disable indented code (False)
125
    - preserve_tabs: bool - Preserve tab characters (False)
126
    - relaxed_headers: bool - Relaxed fenced code headers (False)
127
    
128
    Returns:
129
    SuperFencesExtension instance
130
    """
131

132
class SuperFencesExtension(Extension):
133
    """Enhanced fenced code blocks extension."""
134

135
class SuperFencesPreprocessor(Preprocessor):
136
    """Superfences preprocessor."""
137

138
class SuperFencesTreeprocessor(Treeprocessor):
139
    """Superfences tree processor."""
140

141
def fence_code_format(source, language, css_class, options, md, **kwargs):
142
    """
143
    Default code formatter for fenced blocks.
144
    
145
    Parameters:
146
    - source: str - Source code content
147
    - language: str - Programming language
148
    - css_class: str - CSS class name
149
    - options: dict - Formatter options
150
    - md: Markdown - Markdown instance
151
    
152
    Returns:
153
    str - Formatted HTML
154
    """
155
```
156

157
**Usage Example:**
158

159
```python
160
import markdown
161

162
# Custom formatter example
163
def my_formatter(source, language, css_class, options, md, **kwargs):
164
    return f'<div class="custom-code">{source}</div>'
165

166
md = markdown.Markdown(extensions=[
167
    'pymdownx.superfences'
168
], extension_configs={
169
    'pymdownx.superfences': {
170
        'custom_fences': [
171
            {
172
                'name': 'custom',
173
                'class': 'custom-fence',
174
                'format': my_formatter
175
            }
176
        ]
177
    }
178
})
179
```
180

181
### Arithmatex (Math Rendering)
182

183
LaTeX mathematical expression rendering with support for inline and block math, compatible with MathJax, KaTeX, and other math rendering engines.
184

185
```python { .api }
186
def makeExtension(**kwargs):
187
    """
188
    Create Arithmatex extension for math rendering.
189
    
190
    Configuration:
191
    - inline_syntax: list - Inline math syntax patterns
192
    - block_syntax: list - Block math syntax patterns  
193
    - generic: bool - Use generic output format (True)
194
    - tex_inline_wrap: list - Inline math wrapper
195
    - tex_block_wrap: list - Block math wrapper
196
    - preview: bool - Enable math preview (True)
197
    
198
    Returns:
199
    ArithmatexExtension instance
200
    """
201

202
class ArithmatexExtension(Extension):
203
    """Mathematical expression rendering extension."""
204

205
class InlineArithmatexPattern(InlineProcessor):
206
    """Inline math pattern processor."""
207

208
class BlockArithmatexProcessor(BlockProcessor):
209
    """Block math pattern processor."""
210

211
def arithmatex_inline_format(**kwargs):
212
    """
213
    Configurable inline math formatter.
214
    
215
    Returns:
216
    Callable formatter function
217
    """
218

219
def arithmatex_fenced_format(**kwargs):
220
    """
221
    Configurable fenced math formatter.
222
    
223
    Returns:
224
    Callable formatter function
225
    """
226
```
227

228
**Usage Example:**
229

230
```python
231
import markdown
232

233
# Basic math support
234
md = markdown.Markdown(extensions=['pymdownx.arithmatex'])
235

236
# Inline math: $E = mc^2$  
237
# Block math: $$\sum_{i=1}^n x_i$$
238
text = """
239
Einstein's equation: $E = mc^2$
240

241
$$
242
\\sum_{i=1}^{n} x_i = \\frac{n(n+1)}{2}
243
$$
244
"""
245
html = md.convert(text)
246

247
# Custom formatter for MathJax
248
def mathjax_inline_format(math):
249
    return f'\\({math}\\)'
250

251
def mathjax_block_format(math):
252
    return f'\\[{math}\\]'
253

254
md = markdown.Markdown(extensions=[
255
    'pymdownx.arithmatex'
256
], extension_configs={
257
    'pymdownx.arithmatex': {
258
        'inline_syntax': ['dollar'],
259
        'block_syntax': ['dollar']
260
    }
261
})
262
```
263

264
### Base64 (Image Embedding)
265

266
Converts external images to inline base64 data URIs, enabling self-contained HTML documents without external dependencies.
267

268
```python { .api }
269
def makeExtension(**kwargs):
270
    """
271
    Create B64 extension for base64 image embedding.
272
    
273
    Configuration:
274
    - base_path: str - Base path for resolving relative image paths
275
    -
276
    
277
    Returns:
278
    B64Extension instance
279
    """
280

281
class B64Extension(Extension):
282
    """Base64 image embedding extension."""
283

284
class B64Postprocessor(Postprocessor):
285
    """Image processing for base64 embedding."""
286
```
287

288
**Usage Example:**
289

290
```python
291
import markdown
292

293
md = markdown.Markdown(extensions=['pymdownx.b64'])
294

295
# Images will be converted to base64 data URIs
296
text = "![Alt text](./image.png)"
297
html = md.convert(text)  # Results in <img src="data:image/png;base64,..." />
298
```
299

300
## Advanced Code Configuration
301

302
### Custom Syntax Highlighting
303

304
```python
305
# Language alias configuration
306
extension_configs = {
307
    'pymdownx.highlight': {
308
        'extend_pygments_lang': [
309
            {'name': 'mylang', 'lang': 'python', 'options': {}}
310
        ]
311
    }
312
}
313
```
314

315
### SuperFences Custom Formatters
316

317
```python
318
def diagram_formatter(source, language, css_class, options, md, **kwargs):
319
    """Custom formatter for diagram generation."""
320
    if language == 'diagram':
321
        # Process diagram markup
322
        return f'<div class="diagram">{process_diagram(source)}</div>'
323
    return source
324

325
extension_configs = {
326
    'pymdownx.superfences': {
327
        'custom_fences': [
328
            {
329
                'name': 'diagram',
330
                'class': 'diagram',
331
                'format': diagram_formatter
332
            }
333
        ]
334
    }
335
}
336
```
337

338
### Math Rendering Integration
339

340
```python
341
# MathJax configuration
342
extension_configs = {
343
    'pymdownx.arithmatex': {
344
        'generic': True,
345
        'tex_inline_wrap': ['\\(', '\\)'],
346
        'tex_block_wrap': ['\\[', '\\]']
347
    }
348
}
349

350
# KaTeX configuration  
351
extension_configs = {
352
    'pymdownx.arithmatex': {
353
        'generic': False,
354
        'tex_inline_wrap': ['$', '$'],
355
        'tex_block_wrap': ['$$', '$$']
356
    }
357
}
358
```
359

360
## Types
361

362
```python { .api }
363
from typing import Callable, Dict, List, Optional, Any
364
from markdown import Extension, Preprocessor, InlineProcessor, BlockProcessor, Treeprocessor, Postprocessor
365

366
# Formatter function types
367
CodeFormatter = Callable[[str, str, str, Dict, Any], str]
368
MathFormatter = Callable[[str], str]
369

370
# Configuration types
371
FenceConfig = Dict[str, Any]  # Custom fence configuration
372
PygmentsConfig = Dict[str, Any]  # Pygments configuration options
373
MathSyntax = List[str]  # Math syntax pattern list
374
```