0
# Mistune
1

2
A fast yet powerful Python Markdown parser with renderers and plugins, compatible with sane CommonMark rules. Mistune provides high-performance Markdown parsing with extensive customization through plugins, multiple output formats, and a clean, modular architecture.
3

4
## Package Information
5

6
- **Package Name**: mistune
7
- **Language**: Python  
8
- **Installation**: `pip install mistune`
9
- **Version**: 3.1.4
10
- **Homepage**: https://mistune.lepture.com/
11

12
## Core Imports
13

14
```python
15
import mistune
16
```
17

18
Common patterns for creating parsers:
19

20
```python
21
from mistune import create_markdown, HTMLRenderer, Markdown
22
```
23

24
## Basic Usage
25

26
```python
27
import mistune
28

29
# Simple parsing with default HTML renderer
30
html = mistune.markdown('# Hello **World**')
31
# Output: '<h1>Hello <strong>World</strong></h1>\n'
32

33
# Using the pre-configured HTML parser with common plugins
34
html = mistune.html('# Table\n\n| Name | Age |\n|------|-----|\n| John | 25  |')
35

36
# Create custom parser with specific configuration
37
md = mistune.create_markdown(
38
    escape=False,
39
    renderer='html', 
40
    plugins=['table', 'footnotes', 'strikethrough']
41
)
42
result = md('~~deleted text~~')
43

44
# Parse to AST instead of HTML
45
ast = mistune.markdown('**bold text**', renderer='ast')
46
# Returns: [{'type': 'paragraph', 'children': [{'type': 'strong', 'children': [{'type': 'text', 'raw': 'bold text'}]}]}]
47
```
48

49
## Architecture
50

51
Mistune follows a modular architecture with clear separation of concerns:
52

53
- **Markdown Parser**: Main orchestrator that coordinates parsing and rendering
54
- **Block Parser**: Handles block-level elements (paragraphs, headings, lists, code blocks)
55
- **Inline Parser**: Processes inline elements (bold, italic, links, code spans)
56
- **Renderers**: Convert parsed tokens to output formats (HTML, reStructuredText, Markdown)
57
- **Plugin System**: Extensible architecture for adding new syntax and features
58
- **Directive System**: Advanced plugin system for complex structured content
59

60
This design enables high performance through optimized parsing algorithms while maintaining flexibility through comprehensive plugin and renderer systems.
61

62
## Capabilities
63

64
### Core Parsing
65

66
Main parsing functionality including the Markdown class, factory functions for creating parsers, and the pre-configured HTML parser for common use cases.
67

68
```python { .api }
69
def create_markdown(
70
    escape: bool = True,
71
    hard_wrap: bool = False, 
72
    renderer: Optional[RendererRef] = "html",
73
    plugins: Optional[Iterable[PluginRef]] = None
74
) -> Markdown
75

76
def markdown(
77
    text: str,
78
    escape: bool = True,
79
    renderer: Optional[RendererRef] = "html", 
80
    plugins: Optional[Iterable[Any]] = None
81
) -> Union[str, List[Dict[str, Any]]]
82

83
html: Markdown  # Pre-configured HTML parser with common plugins
84

85
class Markdown:
86
    def __init__(
87
        self,
88
        renderer: Optional[BaseRenderer] = None,
89
        block: Optional[BlockParser] = None,
90
        inline: Optional[InlineParser] = None,
91
        plugins: Optional[Iterable[Plugin]] = None
92
    )
93
    def __call__(self, text: str) -> Union[str, List[Dict[str, Any]]]
94
    def parse(self, text: str) -> Tuple[Union[str, List[Dict[str, Any]]], BlockState]
95
```
96

97
[Core Parsing](./core-parsing.md)
98

99
### Renderers
100

101
Output format renderers for converting parsed Markdown tokens to HTML, reStructuredText, or normalized Markdown. Includes customization options and renderer extension patterns.
102

103
```python { .api }
104
class HTMLRenderer(BaseRenderer):
105
    def __init__(self, escape: bool = True, allow_harmful_protocols: Optional[bool] = None)
106

107
class RSTRenderer(BaseRenderer):
108
    def __init__(self)
109

110
class MarkdownRenderer(BaseRenderer):
111
    def __init__(self)
112

113
class BaseRenderer:
114
    def render_tokens(self, tokens: List[Dict[str, Any]], state: BlockState) -> str
115
    def render_token(self, token: Dict[str, Any], state: BlockState) -> str
116
```
117

118
[Renderers](./renderers.md)
119

120
### Plugin System
121

122
Extensible plugin architecture supporting table syntax, footnotes, formatting extensions, mathematics, task lists, and custom syntax additions. Includes built-in plugins and patterns for creating custom plugins.
123

124
```python { .api }
125
class Plugin(Protocol):
126
    def __call__(self, md: Markdown) -> None
127

128
def import_plugin(name: PluginRef) -> Plugin
129

130
# Built-in plugins
131
PluginRef = Union[str, Plugin]  # "table", "footnotes", "strikethrough", etc.
132
```
133

134
[Plugin System](./plugins.md)
135

136
### Block and Inline Parsing  
137

138
Low-level parsing components for processing block-level and inline Markdown elements. Includes parser state management and custom rule registration.
139

140
```python { .api }
141
class BlockParser(Parser[BlockState]):
142
    def __init__(self, ...)
143
    def parse(self, text: str, state: BlockState) -> None
144

145
class InlineParser(Parser[InlineState]):
146
    def __init__(self, hard_wrap: bool = False, ...)
147
    def process_line(self, text: str, state: InlineState) -> List[Dict[str, Any]]
148

149
class BlockState:
150
    src: str
151
    tokens: List[Dict[str, Any]]
152
    cursor: int
153
    env: MutableMapping[str, Any]
154

155
class InlineState:  
156
    src: str
157
    tokens: List[Dict[str, Any]]
158
    pos: int
159
    env: MutableMapping[str, Any]
160
```
161

162
[Block and Inline Parsing](./parsing.md)
163

164
### Directives System
165

166
Advanced plugin system for structured content blocks with reStructuredText-style and fenced code block-style directive syntax. Supports custom directive creation and built-in directives.
167

168
```python { .api }
169
class DirectivePlugin:
170
    def __init__(self, ...)
171
    
172
class BaseDirective(metaclass=ABCMeta):
173
    def parse(self, block: BlockParser, m: Match[str], state: BlockState) -> int
174
    
175
# Built-in directives: admonition, include, image, figure, toc
176
```
177

178
[Directives System](./directives.md)
179

180
### Utilities and Helpers
181

182
Utility functions for text processing, URL handling, HTML escaping, table of contents generation, and other common Markdown processing tasks.
183

184
```python { .api }
185
def escape(s: str, quote: bool = True) -> str
186
def escape_url(link: str) -> str  
187
def safe_entity(s: str) -> str
188
def unikey(s: str) -> str
189

190
# TOC utilities
191
def add_toc_hook(md: Markdown, min_level: int = 1, max_level: int = 3, heading_id: Optional[Callable] = None) -> None
192
def render_toc_ul(toc_items: List[Dict[str, Any]]) -> str
193
```
194

195
[Utilities and Helpers](./utilities.md)
196

197
## Types
198

199
```python { .api }
200
# Type aliases
201
RendererRef = Union[Literal["html", "ast"], BaseRenderer]
202
PluginRef = Union[str, Plugin]
203

204
# Parser state types  
205
ST = TypeVar('ST', bound=Union[BlockState, InlineState])
206

207
# Token structure
208
Token = Dict[str, Any]  # Contains 'type', optional 'raw', 'children', 'attrs'
209
```