0
# Text Enhancement Extensions
1

2
Extensions that enhance text formatting capabilities including better emphasis handling, insert/delete markup, superscript/subscript support, text highlighting, and intelligent symbol replacement.
3

4
## Capabilities
5

6
### Better Emphasis (BetterEm)
7

8
Provides enhanced emphasis handling with improved asterisk and underscore processing, offering more control over bold and italic formatting behavior.
9

10
```python { .api }
11
def makeExtension(**kwargs):
12
    """
13
    Create BetterEm extension with configurable emphasis handling.
14
    
15
    Configuration:
16
    - smart_enable: str - Enable smart processing ("underscore", "asterisk", "all")
17
    
18
    Returns:
19
    BetterEmExtension instance
20
    """
21

22
class BetterEmExtension(Extension):
23
    """Enhanced emphasis handling extension."""
24

25
class AsteriskProcessor(PatternSequenceProcessor):
26
    """Processes asterisk emphasis patterns."""
27

28
class UnderscoreProcessor(PatternSequenceProcessor):
29
    """Processes underscore emphasis patterns."""
30

31
class SmartAsteriskProcessor(PatternSequenceProcessor):
32
    """Smart asterisk emphasis processor."""
33

34
class SmartUnderscoreProcessor(PatternSequenceProcessor):
35
    """Smart underscore emphasis processor."""
36
```
37

38
**Usage Example:**
39

40
```python
41
import markdown
42

43
# Basic usage
44
md = markdown.Markdown(extensions=['pymdownx.betterem'])
45

46
# With smart processing enabled for all types
47
md = markdown.Markdown(extensions=[
48
    'pymdownx.betterem'
49
], extension_configs={
50
    'pymdownx.betterem': {
51
        'smart_enable': 'all'
52
    }
53
})
54

55
text = "This is **bold** and *italic* text with better_handling."
56
html = md.convert(text)
57
```
58

59
### Caret (Insert and Superscript)
60

61
Adds support for insert tags and superscript formatting using caret (^) syntax, providing semantic markup for text additions and mathematical superscripts.
62

63
```python { .api }
64
def makeExtension(**kwargs):
65
    """
66
    Create Caret extension for insert and superscript support.
67
    
68
    Configuration:
69
    - smart_insert: bool - Enable smart insert processing (True)
70
    - insert: bool - Enable insert tag support (True)
71
    - superscript: bool - Enable superscript support (True)
72
    
73
    Returns:
74
    InsertSupExtension instance
75
    """
76

77
class InsertSupExtension(Extension):
78
    """Insert and superscript extension."""
79

80
class CaretProcessor(PatternSequenceProcessor):
81
    """Full caret processing for both insert and superscript."""
82

83
class CaretSupProcessor(PatternSequenceProcessor):
84
    """Superscript-only caret processor."""
85

86
class CaretInsertProcessor(PatternSequenceProcessor):
87
    """Insert-only caret processor."""
88
```
89

90
**Usage Example:**
91

92
```python
93
import markdown
94

95
md = markdown.Markdown(extensions=['pymdownx.caret'])
96

97
# Insert syntax: ^^inserted text^^
98
# Superscript syntax: ^superscript^
99
text = "E = mc^^2^^ and H^^+^^ ion concentration"
100
html = md.convert(text)
101
```
102

103
### Tilde (Delete and Subscript)
104

105
Enables delete/strikethrough and subscript formatting using tilde (~) syntax, providing semantic markup for text deletions and chemical/mathematical subscripts.
106

107
```python { .api }
108
def makeExtension(**kwargs):
109
    """
110
    Create Tilde extension for delete and subscript support.
111
    
112
    Configuration:
113
    - smart_delete: bool - Enable smart delete processing (True)
114
    - delete: bool - Enable delete tag support (True)
115
    - subscript: bool - Enable subscript support (True)
116
    
117
    Returns:
118
    DeleteSubExtension instance
119
    """
120

121
class DeleteSubExtension(Extension):
122
    """Delete and subscript extension."""
123

124
class TildeProcessor(PatternSequenceProcessor):
125
    """Full tilde processing for both delete and subscript."""
126

127
class TildeDeleteProcessor(PatternSequenceProcessor):
128
    """Delete-only tilde processor."""
129

130
class TildeSubProcessor(PatternSequenceProcessor):
131
    """Subscript-only tilde processor."""
132
```
133

134
**Usage Example:**
135

136
```python
137
import markdown
138

139
md = markdown.Markdown(extensions=['pymdownx.tilde'])
140

141
# Delete syntax: ~~deleted text~~
142
# Subscript syntax: ~subscript~
143
text = "H~2~O is ~~not~~ water"
144
html = md.convert(text)
145
```
146

147
### Mark (Text Highlighting)
148

149
Provides text highlighting capabilities using mark tags, enabling visual emphasis through background highlighting.
150

151
```python { .api }
152
def makeExtension(**kwargs):
153
    """
154
    Create Mark extension for text highlighting.
155
    
156
    Configuration:
157
    - smart_mark: bool - Enable smart mark processing (True)
158
    
159
    Returns:
160
    MarkExtension instance
161
    """
162

163
class MarkExtension(Extension):
164
    """Text highlighting extension."""
165

166
class MarkProcessor(PatternSequenceProcessor):
167
    """Mark text processor."""
168

169
class MarkSmartProcessor(PatternSequenceProcessor):
170
    """Smart mark processor."""
171
```
172

173
**Usage Example:**
174

175
```python
176
import markdown
177

178
md = markdown.Markdown(extensions=['pymdownx.mark'])
179

180
# Highlighting syntax: ==highlighted text==
181
text = "This is ==important information== to remember."
182
html = md.convert(text)
183
```
184

185
### Smart Symbols
186

187
Automatically replaces ASCII character sequences with their Unicode symbol equivalents, enhancing typography with proper symbols for fractions, arrows, quotes, and other special characters.
188

189
```python { .api }
190
def makeExtension(**kwargs):
191
    """
192
    Create SmartSymbols extension for intelligent symbol replacement.
193
    
194
    Configuration:
195
    - smart_symbols: str - Symbol categories to enable
196
    - symbols: dict - Custom symbol mappings
197
    
198
    Returns:
199
    SmartSymbolsExtension instance
200
    """
201

202
class SmartSymbolsExtension(Extension):
203
    """Smart symbol replacement extension."""
204

205
class SmartSymbolsTreeprocessor(Treeprocessor):
206
    """Symbol replacement processor."""
207
```
208

209
**Usage Example:**
210

211
```python
212
import markdown
213

214
md = markdown.Markdown(extensions=['pymdownx.smartsymbols'])
215

216
# Automatic replacements:
217
# --> becomes →
218
# <-- becomes ←
219
# 1/2 becomes ½
220
# (c) becomes ©
221
text = "Copyright (c) 2023. Go to page --> or back <--. Mix 1/2 cup."
222
html = md.convert(text)
223
```
224

225
## Common Configuration Patterns
226

227
### Smart Processing Configuration
228

229
Many text enhancement extensions support "smart" processing modes:
230

231
```python
232
extension_configs = {
233
    'pymdownx.betterem': {'smart_enable': 'all'},
234
    'pymdownx.caret': {'smart_insert': True},
235
    'pymdownx.tilde': {'smart_delete': True},
236
    'pymdownx.mark': {'smart_mark': True}
237
}
238
```
239

240
### Selective Feature Enabling
241

242
Extensions can be configured to enable specific features:
243

244
```python
245
extension_configs = {
246
    'pymdownx.caret': {
247
        'insert': True,      # Enable insert tags
248
        'superscript': False  # Disable superscript
249
    },
250
    'pymdownx.tilde': {
251
        'delete': True,      # Enable delete tags
252
        'subscript': False   # Disable subscript
253
    }
254
}
255
```
256

257
## Types
258

259
```python { .api }
260
from pymdownx.util import PatternSequenceProcessor, PatSeqItem
261
from markdown import Extension, Treeprocessor
262

263
# Configuration types
264
SmartEnableList = List[str]  # List of characters for smart processing
265
SymbolDict = Dict[str, str]  # Symbol replacement mappings
266
ConfigBool = bool           # Boolean configuration option
267
```