0
# Code and Syntax Extras
1

2
Extensions for enhanced code block processing, syntax highlighting, and developer-friendly features that improve the handling of code content in markdown documents.
3

4
## Capabilities
5

6
### Fenced Code Blocks
7

8
GitHub-style fenced code blocks with optional syntax highlighting and language specification.
9

10
```python { .api }
11
# fenced-code-blocks extra - enables ``` style code blocks
12
extras = ["fenced-code-blocks"]
13

14
# highlightjs-lang extra - language specification for highlight.js
15
extras = ["fenced-code-blocks", "highlightjs-lang"]
16
```
17

18
**Usage Examples:**
19

20
```python
21
import markdown2
22

23
# Basic fenced code blocks
24
markdown_text = '''
25
```python
26
def hello_world():
27
    print("Hello, World!")
28
```
29

30
```javascript
31
function helloWorld() {
32
    console.log("Hello, World!");
33
}
34
```
35
'''
36

37
html = markdown2.markdown(markdown_text, extras=["fenced-code-blocks"])
38

39
# With highlight.js language specification
40
html = markdown2.markdown(
41
    markdown_text, 
42
    extras=["fenced-code-blocks", "highlightjs-lang"]
43
)
44
# Adds appropriate class attributes for highlight.js
45
```
46
47
**Fenced Code Block Features:**
48
- Supports language specification: ````python`, ```javascript`, etc.
49
- No indentation required (unlike standard markdown code blocks)
50
- Preserves whitespace and formatting
51
- Can include metadata and options
52
- Compatible with syntax highlighters like Pygments and highlight.js
53

54
### Python Shell Integration
55

56
Special processing for Python interactive shell sessions.
57

58
```python { .api }
59
# pyshell extra - treats unindented Python interactive sessions as code blocks
60
extras = ["pyshell"]
61
```
62

63
**Usage Examples:**
64

65
```python
66
import markdown2
67

68
shell_text = '''
69
>>> import math
70
>>> math.pi
71
3.141592653589793
72
>>> math.sqrt(16)
73
4.0
74
>>> for i in range(3):
75
...     print(f"Number: {i}")
76
... 
77
Number: 0
78
Number: 1
79
Number: 2
80
'''
81

82
html = markdown2.markdown(shell_text, extras=["pyshell"])
83
# Automatically detects and formats Python shell sessions
84
```
85

86
### Syntax Highlighting Integration
87

88
Integration with external syntax highlighting libraries.
89

90
```python { .api }
91
# code-color extra (used in MarkdownWithExtras) - enables Pygments syntax highlighting
92
extras = ["fenced-code-blocks", "code-color"]
93

94
# For highlight.js integration
95
extras = ["fenced-code-blocks", "highlightjs-lang"]
96
```
97

98
**Usage Examples:**
99

100
```python
101
import markdown2
102

103
code_text = '''
104
```python
105
import requests
106
from typing import Dict, List
107

108
def fetch_data(url: str) -> Dict:
109
    """Fetch JSON data from URL."""
110
    response = requests.get(url)
111
    response.raise_for_status()
112
    return response.json()
113

114
class DataProcessor:
115
    def __init__(self, data: List[Dict]):
116
        self.data = data
117
    
118
    def process(self) -> List[str]:
119
        return [item['name'] for item in self.data]
120
```
121
'''
122

123
# With Pygments syntax highlighting (requires pygments package)
124
html = markdown2.markdown(
125
    code_text, 
126
    extras=["fenced-code-blocks", "code-color"]
127
)
128

129
# With highlight.js classes
130
html = markdown2.markdown(
131
    code_text,
132
    extras=["fenced-code-blocks", "highlightjs-lang"]
133
)
134
```
135
136
## Configuration and Options
137

138
### Fenced Code Block Options
139

140
Fenced code blocks support various language specifiers and options:
141

142
```markdown
143
```python
144
# Basic Python code block
145
def example():
146
    pass
147
```
148

149
```python:filename.py
150
# With filename metadata
151
def example():
152
    pass
153
```
154

155
```python {.line-numbers}
156
# With CSS classes
157
def example():
158
    pass
159
```
160
```
161
162
### Language Support
163

164
Common language identifiers supported:
165
- **Python**: `python`, `py`
166
- **JavaScript**: `javascript`, `js`
167
- **TypeScript**: `typescript`, `ts`
168
- **HTML**: `html`, `htm`
169
- **CSS**: `css`
170
- **SQL**: `sql`
171
- **Shell/Bash**: `bash`, `sh`, `shell`
172
- **JSON**: `json`
173
- **XML**: `xml`
174
- **Many more depending on syntax highlighter
175

176
### Pygments Integration
177

178
When using the `code-color` extra with Pygments installed:
179

180
```python
181
import markdown2
182

183
# Requires: pip install pygments
184
html = markdown2.markdown(
185
    code_with_language_blocks,
186
    extras=["fenced-code-blocks", "code-color"]
187
)
188
# Generates full HTML with CSS classes for syntax highlighting
189
```
190

191
### Highlight.js Integration
192

193
When using `highlightjs-lang` extra:
194

195
```python
196
import markdown2
197

198
html = markdown2.markdown(
199
    code_text,
200
    extras=["fenced-code-blocks", "highlightjs-lang"]
201
)
202
# Generates <code class="language-python"> for highlight.js to process
203
```
204

205
## Advanced Code Processing
206

207
### Code-Friendly Text Processing
208

209
Combine code extras with text processing for better code documentation:
210

211
```python
212
import markdown2
213

214
documentation = '''
215
# API Documentation
216

217
The `user_manager.create_user()` function creates a new user:
218

219
```python
220
from user_manager import create_user
221

222
user = create_user(
223
    username="john_doe",
224
    email="john@example.com",
225
    full_name="John Doe"
226
)
227
```
228

229
Note: The function_name_with_underscores won't be emphasized.
230
'''
231

232
html = markdown2.markdown(
233
    documentation,
234
    extras=[
235
        "fenced-code-blocks",
236
        "code-color",        # Syntax highlighting
237
        "code-friendly",     # Don't emphasize underscores
238
        "header-ids"         # For documentation navigation
239
    ]
240
)
241
```
242
243
### Python Shell Documentation
244

245
Document interactive Python sessions:
246

247
```python
248
import markdown2
249

250
tutorial_text = '''
251
# Python Tutorial
252

253
Let's explore some basic Python operations:
254

255
>>> name = "World"
256
>>> message = f"Hello, {name}!"
257
>>> print(message)
258
Hello, World!
259
>>> 
260
>>> numbers = [1, 2, 3, 4, 5]
261
>>> squared = [n**2 for n in numbers]
262
>>> print(squared)
263
[1, 4, 9, 16, 25]
264

265
The `pyshell` extra automatically formats these interactive sessions.
266
'''
267

268
html = markdown2.markdown(
269
    tutorial_text,
270
    extras=["pyshell", "code-friendly", "fenced-code-blocks"]
271
)
272
```
273

274
## Integration Examples
275

276
### Complete Development Documentation Setup
277

278
```python
279
import markdown2
280

281
# Comprehensive setup for code documentation
282
extras = [
283
    "fenced-code-blocks",    # GitHub-style code blocks
284
    "code-color",           # Syntax highlighting with Pygments
285
    "code-friendly",        # Don't emphasize underscores in code
286
    "pyshell",             # Format Python shell sessions
287
    "tables",              # For API reference tables
288
    "header-ids",          # For navigation
289
    "toc"                  # Table of contents
290
]
291

292
processor = markdown2.Markdown(extras=extras)
293

294
# Process documentation files
295
api_docs = processor.convert(api_markdown)
296
tutorial = processor.convert(tutorial_markdown)
297
examples = processor.convert(examples_markdown)
298
```
299

300
### Web Development Integration
301

302
```python
303
import markdown2
304

305
# For web applications with client-side highlighting
306
web_extras = [
307
    "fenced-code-blocks",
308
    "highlightjs-lang",     # Use highlight.js classes
309
    "tables",
310
    "header-ids"
311
]
312

313
html = markdown2.markdown(content, extras=web_extras)
314
# Include highlight.js in your web page to process the code blocks
315
```