0
# Core Parsing and Rendering
1

2
Main parsing functionality for converting markdown text to HTML or tokens, with support for all CommonMark features and configurable parsing behavior.
3

4
## Capabilities
5

6
### Main Parser Class
7

8
The MarkdownIt class is the primary interface for markdown processing, coordinating all parsing components and providing the main API for text conversion.
9

10
```python { .api }
11
class MarkdownIt:
12
    def __init__(
13
        self,
14
        config: str | dict = "commonmark",
15
        options_update: dict = None,
16
        *,
17
        renderer_cls: callable = RendererHTML,
18
    ):
19
        """
20
        Initialize markdown parser.
21
        
22
        Parameters:
23
        - config: preset name ('commonmark', 'default', 'zero', 'gfm-like') or config dict
24
        - options_update: additional options to merge into preset
25
        - renderer_cls: renderer class for output generation
26
        """
27
```
28

29
### Rendering Methods
30

31
Convert markdown text directly to output format (HTML by default).
32

33
```python { .api }
34
def render(self, src: str, env: dict = None) -> str:
35
    """
36
    Render markdown string to HTML.
37
    
38
    Parameters:
39
    - src: markdown text to parse
40
    - env: environment sandbox for metadata (optional)
41
    
42
    Returns:
43
    - str: rendered HTML output
44
    """
45

46
def renderInline(self, src: str, env: dict = None) -> str:
47
    """
48
    Render single paragraph content without wrapping in <p> tags.
49
    
50
    Parameters:
51
    - src: inline markdown text
52
    - env: environment sandbox (optional)
53
    
54
    Returns:
55
    - str: rendered HTML without paragraph wrapper
56
    """
57
```
58

59
**Usage Example:**
60

61
```python
62
from markdown_it import MarkdownIt
63

64
md = MarkdownIt()
65

66
# Full document rendering
67
html = md.render("# Title\n\nParagraph with **bold** text.")
68
# Returns: '<h1>Title</h1>\n<p>Paragraph with <strong>bold</strong> text.</p>\n'
69

70
# Inline rendering (no <p> wrapper)
71
inline_html = md.renderInline("Text with **bold** and _italic_.")
72
# Returns: 'Text with <strong>bold</strong> and <em>italic</em>.'
73
```
74

75
### Parsing Methods
76

77
Convert markdown text to structured token representation for advanced processing.
78

79
```python { .api }
80
def parse(self, src: str, env: dict = None) -> list[Token]:
81
    """
82
    Parse markdown to token stream.
83
    
84
    Parameters:
85
    - src: markdown text to parse
86
    - env: environment sandbox for metadata (optional)
87
    
88
    Returns:
89
    - list[Token]: list of parsed tokens representing document structure
90
    """
91

92
def parseInline(self, src: str, env: dict = None) -> list[Token]:
93
    """
94
    Parse inline content only, skipping block rules.
95
    
96
    Parameters:
97
    - src: inline markdown text
98
    - env: environment sandbox (optional)
99
    
100
    Returns:
101
    - list[Token]: tokens with single inline element containing parsed children
102
    """
103
```
104

105
**Usage Example:**
106

107
```python
108
from markdown_it import MarkdownIt
109

110
md = MarkdownIt()
111

112
# Parse to tokens for processing
113
tokens = md.parse("# Header\n\n*Emphasis* and **strong**.")
114

115
for token in tokens:
116
    print(f"Type: {token.type}, Tag: {token.tag}, Content: {token.content}")
117

118
# Output:
119
# Type: heading_open, Tag: h1, Content: 
120
# Type: inline, Tag: , Content: Header
121
# Type: heading_close, Tag: h1, Content: 
122
# Type: paragraph_open, Tag: p, Content: 
123
# Type: inline, Tag: , Content: *Emphasis* and **strong**.
124
# Type: paragraph_close, Tag: p, Content: 
125
```
126

127
### Parser Components Access
128

129
Access internal parser components for advanced customization.
130

131
```python { .api }
132
# Properties providing access to internal parsers
133
@property
134
def inline(self) -> ParserInline:
135
    """Inline parser instance for processing inline elements."""
136

137
@property  
138
def block(self) -> ParserBlock:
139
    """Block parser instance for processing block elements."""
140

141
@property
142
def core(self) -> ParserCore:
143
    """Core parser instance coordinating parsing pipeline."""
144

145
@property
146
def renderer(self) -> RendererProtocol:
147
    """Renderer instance for output generation."""
148

149
# Dictionary-style access
150
def __getitem__(self, name: str) -> Any:
151
    """Access parser components by name ('inline', 'block', 'core', 'renderer')."""
152
```
153

154
**Usage Example:**
155

156
```python
157
from markdown_it import MarkdownIt
158

159
md = MarkdownIt()
160

161
# Access parser components
162
block_parser = md.block
163
inline_parser = md['inline']
164
renderer = md.renderer
165

166
# Check active rules
167
print("Active block rules:", md.block.ruler.get_active_rules())
168
print("Active inline rules:", md.inline.ruler.get_active_rules())
169
```
170

171
### Environment and Metadata
172

173
The environment parameter provides a sandbox for passing data between parsing stages and retrieving metadata.
174

175
```python { .api }
176
# Environment type definition
177
EnvType = dict[str, Any]
178
```
179

180
**Usage Example:**
181

182
```python
183
from markdown_it import MarkdownIt
184

185
md = MarkdownIt()
186
env = {}
187

188
# Parse with environment to collect metadata
189
html = md.render("[Link text][ref]\n\n[ref]: https://example.com", env)
190

191
# Environment now contains references
192
print(env)
193
# Output: {'references': {'ref': {'href': 'https://example.com', 'title': ''}}}
194
```
195

196
## Error Handling  
197

198
The parser raises exceptions for invalid input or configuration:
199

200
- **TypeError**: Invalid input data types
201
- **KeyError**: Unknown preset names
202
- **ValueError**: Invalid configurations or rule names
203

204
```python
205
try:
206
    md = MarkdownIt('invalid-preset')
207
except KeyError as e:
208
    print(f"Unknown preset: {e}")
209

210
try:
211
    html = md.render(123)  # Invalid input type
212
except TypeError as e:
213
    print(f"Invalid input: {e}")
214
```