0
# Configuration and Presets
1

2
Parser configuration system with built-in presets and rule management for customizing parsing behavior. Allows fine-grained control over which markdown features are enabled and how they are processed.
3

4
## Capabilities
5

6
### Configuration Methods
7

8
Configure the parser with presets and custom options.
9

10
```python { .api }
11
def configure(self, presets: str | dict, options_update: dict = None) -> MarkdownIt:
12
    """
13
    Batch load of all options and component settings.
14
    
15
    Parameters:
16
    - presets: preset name or configuration dictionary
17
    - options_update: additional options to merge into preset
18
    
19
    Returns:
20
    - MarkdownIt: self for method chaining
21
    """
22

23
def set(self, options: dict) -> None:
24
    """
25
    Set parser options directly.
26
    
27
    Parameters:
28
    - options: options dictionary following OptionsType structure
29
    """
30
```
31

32
### Built-in Presets
33

34
Pre-configured parser settings for common use cases.
35

36
```python { .api }
37
# Available preset names (str)
38
PRESETS = [
39
    "commonmark",    # CommonMark specification compliant
40
    "default",       # Default configuration with common features  
41
    "zero",          # Minimal configuration for manual setup
42
    "gfm-like",      # GitHub Flavored Markdown-like features
43
    "js-default"     # Alias for default preset
44
]
45
```
46

47
**Usage Example:**
48

49
```python
50
from markdown_it import MarkdownIt
51

52
# CommonMark compliant (strict spec adherence)
53
md_cm = MarkdownIt('commonmark')
54

55
# Default preset with additional features
56
md_default = MarkdownIt('default')
57

58
# Zero preset for manual configuration
59
md_zero = MarkdownIt('zero').enable(['emphasis', 'link'])
60

61
# GFM-like with tables and strikethrough
62
md_gfm = MarkdownIt('gfm-like')
63

64
# Custom options with preset
65
md_custom = MarkdownIt('commonmark', {
66
    'breaks': True,     # Convert \n to <br>
67
    'html': True,       # Allow HTML tags
68
    'linkify': True     # Auto-convert URLs to links
69
})
70
```
71

72
### Rule Management
73

74
Enable, disable, and manage parsing rules dynamically.
75

76
```python { .api }
77
def enable(self, names: str | list[str], ignoreInvalid: bool = False) -> MarkdownIt:
78
    """
79
    Enable list of rules.
80
    
81
    Parameters:
82
    - names: rule name or list of rule names to enable
83
    - ignoreInvalid: ignore errors when rule not found
84
    
85
    Returns:
86
    - MarkdownIt: self for method chaining
87
    """
88

89
def disable(self, names: str | list[str], ignoreInvalid: bool = False) -> MarkdownIt:
90
    """
91
    Disable list of rules.
92
    
93
    Parameters:
94
    - names: rule name or list of rule names to disable  
95
    - ignoreInvalid: ignore errors when rule not found
96
    
97
    Returns:
98
    - MarkdownIt: self for method chaining
99
    """
100

101
def get_all_rules(self) -> dict[str, list[str]]:
102
    """
103
    Get names of all available rules by parser chain.
104
    
105
    Returns:
106
    - dict: mapping of chain names to rule lists
107
    """
108

109
def get_active_rules(self) -> dict[str, list[str]]:
110
    """
111
    Get names of all currently active rules by parser chain.
112
    
113
    Returns:
114
    - dict: mapping of chain names to active rule lists  
115
    """
116
```
117

118
**Usage Example:**
119

120
```python
121
from markdown_it import MarkdownIt
122

123
md = MarkdownIt('zero')
124

125
# Enable specific rules
126
md.enable(['emphasis', 'strikethrough', 'table'])
127

128
# Disable rules  
129
md.disable(['html_inline', 'html_block'])
130

131
# Chain operations
132
md = (MarkdownIt('commonmark')
133
      .enable(['table', 'strikethrough'])
134
      .disable(['html_inline']))
135

136
# Check rule status
137
print("All rules:", md.get_all_rules())
138
print("Active rules:", md.get_active_rules())
139
```
140

141
### Rule Context Manager
142

143
Temporarily modify rules within a context.
144

145
```python { .api }
146
def reset_rules(self) -> Generator[None, None, None]:
147
    """
148
    Context manager that resets enabled rules on exit.
149
    
150
    Yields:
151
    - None: context for temporary rule modifications
152
    """
153
```
154

155
**Usage Example:**
156

157
```python
158
from markdown_it import MarkdownIt
159

160
md = MarkdownIt('commonmark')
161

162
# Temporarily disable rules
163
with md.reset_rules():
164
    md.disable(['emphasis', 'strong'])
165
    # Process with limited rules
166
    html = md.render("**bold** and *italic*")
167
    print(html)  # No emphasis processing
168

169
# Rules are restored after context exit
170
html = md.render("**bold** and *italic*") 
171
print(html)  # Full emphasis processing restored
172
```
173

174
### Plugin System
175

176
Load and configure plugins to extend parsing capabilities.
177

178
```python { .api }
179
def use(self, plugin: callable, *params, **options) -> MarkdownIt:
180
    """
181
    Load plugin with parameters.
182
    
183
    Parameters:
184
    - plugin: plugin function that modifies parser
185
    - params: positional arguments for plugin
186
    - options: keyword arguments for plugin
187
    
188
    Returns:
189
    - MarkdownIt: self for method chaining
190
    """
191
```
192

193
**Usage Example:**
194

195
```python
196
from markdown_it import MarkdownIt
197

198
def custom_plugin(md, option1, option2=None):
199
    """Custom plugin that modifies parser behavior."""
200
    # Plugin implementation
201
    pass
202

203
md = (MarkdownIt('commonmark')
204
      .use(custom_plugin, 'param1', option2='value'))
205

206
# Chain multiple plugins
207
md.use(plugin1).use(plugin2, arg1, arg2)
208
```
209

210
## Parser Options
211

212
Complete options structure for fine-grained control.
213

214
```python { .api }
215
class OptionsType(TypedDict):
216
    maxNesting: int             # Recursion limit (default: 20-100)
217
    html: bool                  # Enable HTML tags in source
218
    linkify: bool              # Auto-convert URLs to links  
219
    typographer: bool          # Enable smart quotes and replacements
220
    quotes: str               # Quote replacement characters
221
    xhtmlOut: bool            # Use XHTML self-closing tags
222
    breaks: bool              # Convert \n to <br>
223
    langPrefix: str           # CSS prefix for code blocks
224
    highlight: callable | None # Syntax highlighter function
225
```
226

227
### Preset Configurations
228

229
Details of built-in preset configurations:
230

231
**CommonMark Preset:**
232
```python
233
{
234
    "options": {
235
        "maxNesting": 20,
236
        "html": True,
237
        "linkify": False, 
238
        "typographer": False,
239
        "xhtmlOut": True,
240
        "breaks": False
241
    },
242
    "components": {
243
        "core": {"rules": ["normalize", "block", "inline", "text_join"]},
244
        "block": {"rules": ["blockquote", "code", "fence", "heading", "hr", 
245
                           "html_block", "lheading", "list", "reference", "paragraph"]},
246
        "inline": {"rules": ["autolink", "backticks", "emphasis", "entity", 
247
                            "escape", "html_inline", "image", "link", "newline", "text"]}
248
    }
249
}
250
```
251

252
**Default Preset:**
253
```python
254
{
255
    "options": {
256
        "maxNesting": 100,
257
        "html": False,
258
        "linkify": False,
259
        "typographer": False, 
260
        "xhtmlOut": False,
261
        "breaks": False
262
    },
263
    "components": {}  # Enables all available rules
264
}
265
```
266

267
**Zero Preset:**
268
```python
269
{
270
    "options": {
271
        "maxNesting": 20,
272
        "html": False,
273
        "linkify": False,
274
        "typographer": False,
275
        "xhtmlOut": False, 
276
        "breaks": False
277
    },
278
    "components": {
279
        "core": {"rules": ["normalize", "block", "inline", "text_join"]},
280
        "block": {"rules": ["paragraph"]},
281
        "inline": {"rules": ["text"]}
282
    }
283
}
284
```
285

286
**GFM-like Preset:**
287
```python
288
# Extends CommonMark with:
289
# - Linkification
290
# - Tables
291
# - Strikethrough
292
# - HTML enabled
293
```
294

295
**Usage Example:**
296

297
```python
298
from markdown_it import MarkdownIt
299

300
# Custom options with specific features
301
md = MarkdownIt('zero', {
302
    'html': True,
303
    'breaks': True,
304
    'typographer': True,
305
    'quotes': '«»‹›',  # French quotes
306
    'highlight': custom_highlighter
307
})
308

309
# Enable only needed rules
310
md.enable(['emphasis', 'strong', 'link', 'autolink'])
311

312
html = md.render("""
313
"Smart quotes" and auto-links: https://example.com
314
**Bold** and *italic* text.
315
""")
316
```