0
# Special Content Extras
1
2
Extensions for specialized content types including mathematical expressions, diagrams, interactive elements, alerts, and advanced formatting that extend markdown beyond standard text processing.
3
4
## Capabilities
5
6
### Mathematical Expressions
7
8
Support for LaTeX mathematical notation and expressions.
9
10
```python { .api }
11
# latex extra - LaTeX math expression support
12
extras = ["latex"]
13
```
14
15
**Usage Examples:**
16
17
```python
18
import markdown2
19
20
# Requires latex2mathml package: pip install latex2mathml
21
math_text = '''
22
The quadratic formula is: $x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}$
23
24
Block math equation:
25
$$
26
\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}
27
$$
28
29
Matrix notation:
30
$$
31
\\begin{pmatrix}
32
a & b \\\\
33
c & d
34
\\end{pmatrix}
35
$$
36
'''
37
38
html = markdown2.markdown(math_text, extras=["latex"])
39
# Converts LaTeX to MathML for web display
40
```
41
42
### Diagram Generation
43
44
Support for various diagram types including Mermaid and WaveDrom.
45
46
```python { .api }
47
# mermaid extra - Mermaid diagram support
48
extras = ["mermaid"]
49
50
# wavedrom extra - WaveDrom digital timing diagrams
51
extras = ["wavedrom"]
52
53
# With configuration
54
extras = {
55
"wavedrom": {
56
"config": {"theme": "default"}
57
}
58
}
59
```
60
61
**Usage Examples:**
62
63
```python
64
import markdown2
65
66
# Mermaid diagrams
67
mermaid_text = '''
68
```mermaid
69
graph TD
70
A[Start] --> B{Decision}
71
B -->|Yes| C[Action 1]
72
B -->|No| D[Action 2]
73
C --> E[End]
74
D --> E
75
```
76
77
```mermaid
78
sequenceDiagram
79
participant A as Alice
80
participant B as Bob
81
A->>B: Hello Bob!
82
B->>A: Hello Alice!
83
```
84
'''
85
86
html = markdown2.markdown(mermaid_text, extras=["mermaid", "fenced-code-blocks"])
87
88
# WaveDrom timing diagrams (requires wavedrom package)
89
wavedrom_text = '''
90
```wavedrom
91
{
92
"signal": [
93
{"name": "clk", "wave": "p.....|..."},
94
{"name": "dat", "wave": "..2.3.|=.4", "data": ["head", "body", "tail"]},
95
{"name": "req", "wave": "0.1..0|1.0"}
96
]
97
}
98
```
99
'''
100
101
html = markdown2.markdown(wavedrom_text, extras=["wavedrom", "fenced-code-blocks"])
102
```
103
104
### Alert and Admonition Systems
105
106
GitHub-style alerts and reStructuredText-style admonitions for highlighting important content.
107
108
```python { .api }
109
# alerts extra - GitHub-style alerts
110
extras = ["alerts"]
111
112
# admonitions extra - RST-style admonitions
113
extras = ["admonitions"]
114
```
115
116
**Usage Examples:**
117
118
```python
119
import markdown2
120
121
# GitHub-style alerts
122
alerts_text = '''
123
> [!NOTE]
124
> This is a note alert with important information.
125
126
> [!WARNING]
127
> This is a warning alert about potential issues.
128
129
> [!TIP]
130
> This is a tip alert with helpful suggestions.
131
132
> [!IMPORTANT]
133
> This is an important alert for critical information.
134
135
> [!CAUTION]
136
> This is a caution alert about dangerous operations.
137
'''
138
139
html = markdown2.markdown(alerts_text, extras=["alerts"])
140
141
# RST-style admonitions
142
admonitions_text = '''
143
!!! note "Optional Title"
144
This is a note admonition with an optional title.
145
146
It can contain multiple paragraphs and formatting.
147
148
!!! warning
149
This is a warning without a custom title.
150
151
!!! tip "Pro Tip"
152
Advanced users can configure this feature
153
for better performance.
154
'''
155
156
html = markdown2.markdown(admonitions_text, extras=["admonitions"])
157
```
158
159
### Interactive Content
160
161
Support for spoilers, collapsible content, and special formatting.
162
163
```python { .api }
164
# spoiler extra - Stack Overflow style spoiler blocks
165
extras = ["spoiler"]
166
167
# telegram-spoiler extra - Telegram-style spoiler text
168
extras = ["telegram-spoiler"]
169
```
170
171
**Usage Examples:**
172
173
```python
174
import markdown2
175
176
# Stack Overflow style spoilers
177
spoiler_text = '''
178
Here's a puzzle for you:
179
180
>! The answer is 42.
181
>!
182
>! This is the spoiler content that will be hidden
183
>! until the user clicks to reveal it.
184
185
Click to reveal the solution above.
186
'''
187
188
html = markdown2.markdown(spoiler_text, extras=["spoiler"])
189
190
# Telegram-style spoilers
191
telegram_text = '''
192
The movie ending is ||completely unexpected||.
193
194
The main character ||dies in the final scene||.
195
'''
196
197
html = markdown2.markdown(telegram_text, extras=["telegram-spoiler"])
198
```
199
200
### Numbering and References
201
202
Sequential numbering system for figures, tables, equations, and other elements.
203
204
```python { .api }
205
# numbering extra - generic counter support for sequential numbering
206
extras = ["numbering"]
207
```
208
209
**Usage Examples:**
210
211
```python
212
import markdown2
213
214
numbering_text = '''
215
See %Figure 1% for the architecture overview.
216
217
%Figure 1%: System Architecture
218
219
220
The equation %Equation 1% shows the relationship:
221
222
%Equation 1%: $E = mc^2$
223
224
Refer to %Table 1% for performance metrics:
225
226
%Table 1%: Performance Results
227
| Test | Result |
228
|------|--------|
229
| A | 95% |
230
| B | 87% |
231
'''
232
233
html = markdown2.markdown(numbering_text, extras=["numbering", "tables"])
234
```
235
236
## Advanced Special Content Processing
237
238
### Scientific Document Processing
239
240
Combine mathematical and diagram extras for scientific documentation:
241
242
```python
243
import markdown2
244
245
# Scientific paper processor
246
scientific_processor = markdown2.Markdown(
247
extras=[
248
"latex", # Mathematical expressions
249
"mermaid", # Flow charts and diagrams
250
"wavedrom", # Timing diagrams
251
"tables", # Data tables
252
"footnotes", # Citations
253
"numbering", # Figure/equation numbering
254
"header-ids", # Section references
255
"toc", # Table of contents
256
"admonitions" # Warnings and notes
257
]
258
)
259
260
scientific_document = '''
261
---
262
title: "Analysis of Quantum Computing Algorithms"
263
author: "Dr. Jane Smith"
264
---
265
266
# Introduction
267
268
This paper analyzes quantum algorithms with focus on Grover's algorithm.
269
270
!!! note "Prerequisites"
271
Readers should be familiar with linear algebra and quantum mechanics.
272
273
## Grover's Algorithm
274
275
The algorithm provides quadratic speedup: $O(\\sqrt{N})$ vs classical $O(N)$.
276
277
%Figure 1%: Algorithm Flow
278
```mermaid
279
graph TD
280
A[Initialize] --> B[Apply H gates]
281
B --> C[Oracle]
282
C --> D[Diffusion]
283
D --> E{Converged?}
284
E -->|No| C
285
E -->|Yes| F[Measure]
286
```
287
288
The probability amplitude is given by:
289
$$P = \\sin^2\\left((2k+1)\\frac{\\theta}{2}\\right)$$
290
291
> [!WARNING]
292
> Quantum decoherence can affect algorithm performance.
293
'''
294
295
html = scientific_processor.convert(scientific_document)
296
```
297
298
### Documentation with Interactive Elements
299
300
Create rich documentation with alerts, spoilers, and diagrams:
301
302
```python
303
import markdown2
304
305
# Documentation processor with interactive elements
306
docs_processor = markdown2.Markdown(
307
extras=[
308
"alerts", # GitHub-style alerts
309
"admonitions", # RST-style admonitions
310
"spoiler", # Collapsible spoilers
311
"mermaid", # Diagrams
312
"fenced-code-blocks", # Code examples
313
"tables", # Reference tables
314
"header-ids", # Navigation
315
"toc" # Table of contents
316
]
317
)
318
319
interactive_docs = '''
320
# API Documentation
321
322
> [!IMPORTANT]
323
> This API requires authentication for all endpoints.
324
325
## Authentication Flow
326
327
```mermaid
328
sequenceDiagram
329
participant C as Client
330
participant A as Auth Server
331
participant R as Resource Server
332
333
C->>A: Request token
334
A->>C: Return token
335
C->>R: API call with token
336
R->>C: Return data
337
```
338
339
!!! tip "Best Practice"
340
Always store tokens securely and refresh them before expiration.
341
342
### Security Considerations
343
344
>! The API key should never be exposed in client-side code.
345
>! Use environment variables or secure key management systems.
346
347
### Error Handling
348
349
> [!WARNING]
350
> Rate limiting applies to all endpoints (100 requests/minute).
351
352
| Status Code | Meaning | Action |
353
|-------------|---------|--------|
354
| 200 | Success | Continue |
355
| 401 | Unauthorized | Check token |
356
| 429 | Rate Limited | Wait and retry |
357
'''
358
359
html = docs_processor.convert(interactive_docs)
360
```
361
362
## Configuration Options
363
364
### LaTeX Configuration
365
366
Requires `latex2mathml` package and Python 3.8.1+:
367
368
```bash
369
pip install latex2mathml
370
```
371
372
### WaveDrom Configuration
373
374
Requires `wavedrom` package:
375
376
```bash
377
pip install wavedrom
378
```
379
380
```python
381
wavedrom_config = {
382
"config": {
383
"theme": "default", # or "dark"
384
"width": 800,
385
"height": 400
386
}
387
}
388
```
389
390
### Mermaid Integration
391
392
Works with fenced code blocks and can be rendered client-side:
393
394
```html
395
<!-- Include Mermaid.js in your HTML -->
396
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
397
<script>mermaid.initialize({startOnLoad:true});</script>
398
```
399
400
## Integration Examples
401
402
### Complete Rich Content Processor
403
404
```python
405
import markdown2
406
407
# Full-featured content processor
408
rich_processor = markdown2.Markdown(
409
extras={
410
# Math and diagrams
411
"latex": None,
412
"mermaid": None,
413
"wavedrom": None,
414
415
# Alerts and admonitions
416
"alerts": None,
417
"admonitions": None,
418
"spoiler": None,
419
420
# Structure and layout
421
"tables": None,
422
"footnotes": None,
423
"header-ids": None,
424
"toc": {"depth": 3},
425
"metadata": None,
426
427
# Code and syntax
428
"fenced-code-blocks": None,
429
"code-color": None,
430
431
# Text processing
432
"smarty-pants": None,
433
"break-on-newline": None
434
}
435
)
436
437
# Process rich content document
438
html = rich_processor.convert(rich_content_markdown)
439
440
# Access all features
441
if html.metadata:
442
print("Document metadata available")
443
if html.toc_html:
444
print("Table of contents generated")
445
```
446
447
### Web Application Integration
448
449
```python
450
import markdown2
451
452
def process_user_content(content, allow_math=False, allow_diagrams=False):
453
"""Process user-generated content with configurable features."""
454
455
base_extras = [
456
"fenced-code-blocks",
457
"tables",
458
"header-ids",
459
"alerts",
460
"break-on-newline"
461
]
462
463
if allow_math:
464
base_extras.append("latex")
465
466
if allow_diagrams:
467
base_extras.extend(["mermaid", "wavedrom"])
468
469
processor = markdown2.Markdown(
470
extras=base_extras,
471
safe_mode="escape" # Security for user content
472
)
473
474
return processor.convert(content)
475
476
# Usage
477
user_post = process_user_content(user_markdown, allow_math=True)
478
admin_doc = process_user_content(admin_markdown, allow_math=True, allow_diagrams=True)
479
```