0
# Text Processing Extras
1
2
Extensions that modify how text elements are processed, including line break behavior, emphasis handling, typography enhancements, and text formatting options.
3
4
## Capabilities
5
6
### Line Break Control
7
8
Control how line breaks and newlines are handled in the markdown text.
9
10
```python { .api }
11
# breaks extra - configurable line break behavior
12
extras = {
13
"breaks": {
14
"on_newline": True, # Replace single newlines with <br>
15
"on_backslash": True # Replace backslash at end of line with <br>
16
}
17
}
18
19
# break-on-newline extra - alias for breaks with on_newline=True
20
extras = ["break-on-newline"]
21
```
22
23
**Usage Examples:**
24
25
```python
26
import markdown2
27
28
# Enable line breaks on newlines (GitHub-style)
29
text = """First line
30
Second line
31
Third line"""
32
33
html = markdown2.markdown(text, extras=["break-on-newline"])
34
# Result: <p>First line<br>Second line<br>Third line</p>
35
36
# Configure both newline and backslash breaks
37
html = markdown2.markdown(
38
"Line 1\\\nLine 2\nLine 3",
39
extras={"breaks": {"on_newline": True, "on_backslash": True}}
40
)
41
```
42
43
### Emphasis and Bold Processing
44
45
Control how emphasis markers (*_*) are processed in text.
46
47
```python { .api }
48
# code-friendly extra - disable _ and __ for em and strong
49
extras = ["code-friendly"]
50
51
# middle-word-em extra - control emphasis in middle of words
52
extras = {
53
"middle-word-em": True # Allow emphasis in middle of words (default)
54
# or False to disable (this_text_here won't become this<em>text</em>here)
55
}
56
```
57
58
**Usage Examples:**
59
60
```python
61
import markdown2
62
63
# Code-friendly: disable underscore emphasis
64
code_text = "function_name and another_function_name"
65
html = markdown2.markdown(code_text, extras=["code-friendly"])
66
# Underscores won't be treated as emphasis markers
67
68
# Control middle-word emphasis
69
text = "this_is_emphasized_text"
70
html = markdown2.markdown(
71
text,
72
extras={"middle-word-em": False}
73
)
74
# Won't convert to: this<em>is</em>emphasized<em>text
75
```
76
77
### Typography Enhancement
78
79
Smart typography replacements for professional document formatting.
80
81
```python { .api }
82
# smarty-pants extra - smart quotes and punctuation
83
extras = ["smarty-pants"]
84
```
85
86
**Usage Examples:**
87
88
```python
89
import markdown2
90
91
text = '''
92
"Hello," she said. "How are you?"
93
He replied, "I'm fine -- thanks for asking..."
94
The 1990's were great.
95
'''
96
97
html = markdown2.markdown(text, extras=["smarty-pants"])
98
# Converts:
99
# " " to curly quotes
100
# -- to en dash
101
# --- to em dash
102
# ... to ellipsis
103
# 's to curly apostrophe
104
```
105
106
### Text Formatting Extensions
107
108
Additional text formatting options beyond standard markdown.
109
110
```python { .api }
111
# strike extra - strikethrough text with double tildes
112
extras = ["strike"]
113
114
# underline extra - underline text support
115
extras = ["underline"]
116
```
117
118
**Usage Examples:**
119
120
```python
121
import markdown2
122
123
# Strikethrough text
124
text = "This is ~~strikethrough~~ text"
125
html = markdown2.markdown(text, extras=["strike"])
126
# Result: This is <del>strikethrough</del> text
127
128
# Underline text (if supported by implementation)
129
text = "This is _underlined_ text"
130
html = markdown2.markdown(text, extras=["underline"])
131
```
132
133
### List Processing
134
135
Control how lists are processed and formatted.
136
137
```python { .api }
138
# cuddled-lists extra - allow lists cuddled to preceding paragraphs
139
extras = ["cuddled-lists"]
140
```
141
142
**Usage Examples:**
143
144
```python
145
import markdown2
146
147
text = """This is a paragraph.
148
- List item 1
149
- List item 2
150
- List item 3"""
151
152
# Without cuddled-lists: paragraph and list are separate blocks
153
html1 = markdown2.markdown(text)
154
155
# With cuddled-lists: list can be cuddled to paragraph
156
html2 = markdown2.markdown(text, extras=["cuddled-lists"])
157
```
158
159
## Configuration Options
160
161
### Breaks Extra Configuration
162
163
The `breaks` extra accepts a dictionary with the following options:
164
165
```python
166
breaks_config = {
167
"on_newline": True, # Convert single newlines to <br> tags
168
"on_backslash": True # Convert backslash-newline to <br> tags
169
}
170
```
171
172
### Middle-Word Emphasis Configuration
173
174
Control emphasis behavior in the middle of words:
175
176
```python
177
# Allow emphasis in middle of words (default behavior)
178
extras = {"middle-word-em": True}
179
180
# Disable emphasis in middle of words (better for code/technical docs)
181
extras = {"middle-word-em": False}
182
```
183
184
## Combined Usage Examples
185
186
```python
187
import markdown2
188
189
# Combine multiple text processing extras
190
text = """
191
"Hello world" -- this is a test.
192
193
Some code_with_underscores here.
194
This is ~~deleted~~ text.
195
196
First line
197
Second line
198
Third line
199
"""
200
201
html = markdown2.markdown(
202
text,
203
extras=[
204
"smarty-pants", # Smart quotes and punctuation
205
"code-friendly", # Don't treat underscores as emphasis
206
"strike", # Support strikethrough
207
"break-on-newline", # Convert newlines to <br>
208
"cuddled-lists" # Allow cuddled list formatting
209
]
210
)
211
212
# Or with configuration options
213
html = markdown2.markdown(
214
text,
215
extras={
216
"smarty-pants": None,
217
"code-friendly": None,
218
"strike": None,
219
"breaks": {"on_newline": True, "on_backslash": True},
220
"middle-word-em": False
221
}
222
)
223
```
224
225
### File Variable Processing
226
227
Automatic detection and processing of Emacs-style file variables for enabling extras.
228
229
```python { .api }
230
# use-file-vars extra - look for Emacs-style file variables
231
extras = ["use-file-vars"]
232
```
233
234
**Usage Examples:**
235
236
```python
237
import markdown2
238
239
# Markdown content with Emacs-style variables
240
content_with_vars = '''<!--
241
-*- markdown-extras: footnotes,tables,fenced-code-blocks -*-
242
-->
243
244
# Document Title
245
246
This document has footnotes[^1] and tables.
247
248
| Col1 | Col2 |
249
|------|------|
250
| Data | More |
251
252
[^1]: This is a footnote enabled by file variables.
253
'''
254
255
# File variables are automatically detected and applied
256
html = markdown2.markdown(content_with_vars, use_file_vars=True)
257
# Equivalent to: extras=["footnotes", "tables", "fenced-code-blocks"]
258
```
259
260
## Compatibility Notes
261
262
- **`code-friendly`**: Particularly useful for technical documentation where underscores are common in code
263
- **`break-on-newline`**: Mimics GitHub-flavored markdown line break behavior
264
- **`smarty-pants`**: Based on the original SmartyPants by John Gruber
265
- **`cuddled-lists`**: Allows more flexible list formatting similar to some other markdown processors