0
# Core Parsing
1
2
Main parsing functionality that forms the foundation of mistune's Markdown processing. Provides factory functions for creating parsers, the main Markdown class for custom parsing workflows, and a pre-configured HTML parser for common use cases.
3
4
## Capabilities
5
6
### Factory Functions
7
8
Functions for creating configured Markdown parser instances with specific renderers, plugins, and options.
9
10
```python { .api }
11
def create_markdown(
12
escape: bool = True,
13
hard_wrap: bool = False,
14
renderer: Optional[RendererRef] = "html",
15
plugins: Optional[Iterable[PluginRef]] = None
16
) -> Markdown:
17
"""
18
Create a Markdown instance based on the given condition.
19
20
Parameters:
21
- escape: Boolean. If using html renderer, escape html.
22
- hard_wrap: Boolean. Break every new line into <br>.
23
- renderer: renderer instance, default is HTMLRenderer. Can be "html", "ast", or BaseRenderer instance.
24
- plugins: List of plugins to use.
25
26
Returns:
27
Configured Markdown instance for reuse.
28
"""
29
```
30
31
Usage example:
32
33
```python
34
import mistune
35
36
# Create parser with custom configuration
37
md = mistune.create_markdown(
38
escape=False,
39
hard_wrap=True,
40
renderer='html',
41
plugins=['table', 'footnotes', 'strikethrough']
42
)
43
44
# Reuse the parser instance
45
html1 = md('# Heading 1')
46
html2 = md('**Bold text**')
47
```
48
49
### Convenience Function
50
51
High-level function for one-off parsing with caching for performance optimization.
52
53
```python { .api }
54
def markdown(
55
text: str,
56
escape: bool = True,
57
renderer: Optional[RendererRef] = "html",
58
plugins: Optional[Iterable[Any]] = None
59
) -> Union[str, List[Dict[str, Any]]]:
60
"""
61
Parse markdown text with caching for performance.
62
63
Parameters:
64
- text: Markdown text to parse
65
- escape: Boolean. If using html renderer, escape html.
66
- renderer: renderer instance, default is HTMLRenderer. Can be "html", "ast", or BaseRenderer instance.
67
- plugins: List of plugins to use.
68
69
Returns:
70
Parsed result as string (HTML/RST) or list of tokens (AST).
71
"""
72
```
73
74
Usage example:
75
76
```python
77
import mistune
78
79
# Simple HTML parsing
80
html = mistune.markdown('# Hello **World**')
81
# Output: '<h1>Hello <strong>World</strong></h1>\n'
82
83
# Parse to AST
84
ast = mistune.markdown('**bold**', renderer='ast')
85
# Output: [{'type': 'paragraph', 'children': [{'type': 'strong', 'children': [{'type': 'text', 'raw': 'bold'}]}]}]
86
87
# With plugins
88
html = mistune.markdown('~~strikethrough~~', plugins=['strikethrough'])
89
```
90
91
### Pre-configured Parser
92
93
Ready-to-use HTML parser instance with common plugins enabled for immediate use.
94
95
```python { .api }
96
html: Markdown
97
# Pre-configured Markdown instance with HTMLRenderer and plugins:
98
# ["strikethrough", "footnotes", "table", "speedup"]
99
```
100
101
Usage example:
102
103
```python
104
import mistune
105
106
# Use pre-configured parser directly
107
result = mistune.html('''
108
# Table Example
109
110
| Name | Age |
111
|------|-----|
112
| John | 25 |
113
| Jane | 30 |
114
115
Text with ~~strikethrough~~.
116
''')
117
```
118
119
### Markdown Class
120
121
Main parser class that orchestrates the parsing process, coordinating block parsing, inline parsing, rendering, and plugin execution.
122
123
```python { .api }
124
class Markdown:
125
"""
126
Markdown instance to convert Markdown text into HTML or other formats.
127
128
Attributes:
129
- renderer: Optional[BaseRenderer] - Output renderer
130
- block: BlockParser - Block-level parser
131
- inline: InlineParser - Inline-level parser
132
- before_parse_hooks: List[Callable] - Hooks executed before parsing
133
- before_render_hooks: List[Callable] - Hooks executed before rendering
134
- after_render_hooks: List[Callable] - Hooks executed after rendering
135
"""
136
137
def __init__(
138
self,
139
renderer: Optional[BaseRenderer] = None,
140
block: Optional[BlockParser] = None,
141
inline: Optional[InlineParser] = None,
142
plugins: Optional[Iterable[Plugin]] = None
143
):
144
"""
145
Initialize Markdown parser.
146
147
Parameters:
148
- renderer: A renderer to convert parsed tokens
149
- block: Block level syntax parser
150
- inline: Inline level syntax parser
151
- plugins: Mistune plugins to use
152
"""
153
154
def __call__(self, text: str) -> Union[str, List[Dict[str, Any]]]:
155
"""
156
Parse Markdown text and return rendered output.
157
158
Parameters:
159
- text: Markdown text to parse
160
161
Returns:
162
Rendered output (string for renderers, token list for AST)
163
"""
164
165
def parse(self, text: str) -> Tuple[Union[str, List[Dict[str, Any]]], BlockState]:
166
"""
167
Parse Markdown text and return both output and state.
168
169
Parameters:
170
- text: Markdown text to parse
171
172
Returns:
173
Tuple of (rendered_output, final_block_state)
174
"""
175
176
def read(self, filepath: str, encoding: str = "utf-8", state: Optional[BlockState] = None) -> Tuple[Union[str, List[Dict[str, Any]]], BlockState]:
177
"""
178
Read and parse Markdown file.
179
180
Parameters:
181
- filepath: Path to Markdown file to read
182
- encoding: File encoding (default: utf-8)
183
- state: Optional BlockState to use
184
185
Returns:
186
Tuple of (rendered_output, final_block_state)
187
"""
188
189
def use(self, plugin: Plugin) -> None:
190
"""
191
Use a plugin to extend parser functionality.
192
193
Parameters:
194
- plugin: Plugin to add to this parser
195
"""
196
```
197
198
Usage example:
199
200
```python
201
from mistune import Markdown, HTMLRenderer, BlockParser, InlineParser
202
203
# Create custom parser instance
204
renderer = HTMLRenderer(escape=False)
205
block = BlockParser()
206
inline = InlineParser(hard_wrap=True)
207
208
md = Markdown(renderer=renderer, block=block, inline=inline)
209
210
# Parse text
211
result = md('# Hello\n\nThis is **bold**.')
212
213
# Parse with state access
214
output, state = md.parse('# Heading\n\nParagraph text.')
215
print(f"Tokens: {state.tokens}")
216
print(f"Environment: {state.env}")
217
```
218
219
## Hook System
220
221
The Markdown class provides a hook system for extending functionality at different stages of processing:
222
223
```python { .api }
224
# Hook types available on Markdown instances
225
before_parse_hooks: List[Callable[[Markdown, BlockState], None]]
226
before_render_hooks: List[Callable[[Markdown, BlockState], Any]]
227
after_render_hooks: List[Callable[[Markdown, Union[str, List[Dict]], BlockState], Union[str, List[Dict]]]]
228
```
229
230
Usage example:
231
232
```python
233
def custom_hook(md, state):
234
print(f"Processing {len(state.tokens)} tokens")
235
236
md = mistune.create_markdown()
237
md.before_render_hooks.append(custom_hook)
238
result = md('# Example text')
239
```