0
# markdown2
1
2
markdown2 is a fast and complete Python implementation of Markdown that translates easy-to-read, easy-to-write structured text format into HTML. It closely matches the behavior of the original Perl-implemented Markdown.pl while providing extensive customization through 25+ built-in extras (extensions) for enhanced functionality like syntax highlighting, tables, footnotes, header IDs, and many advanced features.
3
4
## Package Information
5
6
- **Package Name**: markdown2
7
- **Language**: Python
8
- **Installation**: `pip install markdown2` or `pip install markdown2[all]` (with optional dependencies)
9
- **Python Requirements**: Python 3.9+
10
11
## Core Imports
12
13
```python
14
import markdown2
15
```
16
17
For class-based usage:
18
19
```python
20
from markdown2 import Markdown
21
```
22
23
For specific components:
24
25
```python
26
from markdown2 import Markdown, MarkdownWithExtras, UnicodeWithAttrs, MarkdownError
27
```
28
29
## Basic Usage
30
31
```python
32
import markdown2
33
34
# Simple conversion
35
html = markdown2.markdown("**bold text** and *italic text*")
36
print(html) # <p><strong>bold text</strong> and <em>italic text</em></p>
37
38
# Convert a file
39
html = markdown2.markdown_path("document.md")
40
41
# With extras (extensions)
42
html = markdown2.markdown(
43
"```python\nprint('hello')\n```",
44
extras=["fenced-code-blocks", "code-friendly"]
45
)
46
47
# Reusable processor
48
markdowner = Markdown(extras=["footnotes", "tables", "header-ids"])
49
html1 = markdowner.convert(text1)
50
html2 = markdowner.convert(text2)
51
52
# Pre-configured processor with common extras
53
from markdown2 import MarkdownWithExtras
54
markdowner = MarkdownWithExtras() # includes footnotes, fenced-code-blocks
55
html = markdowner.convert(markdown_text)
56
```
57
58
## Architecture
59
60
markdown2 uses a processing pipeline with defined stages and an extensible extras system:
61
62
- **Core Functions**: `markdown()` and `markdown_path()` for simple conversions
63
- **Markdown Class**: Reusable processor with configurable options and extras
64
- **Extras System**: Modular extensions that hook into processing stages
65
- **UnicodeWithAttrs**: Enhanced string return type with optional metadata and TOC attributes
66
- **Processing Stages**: Ordered pipeline from preprocessing to final HTML output
67
68
## Capabilities
69
70
### Core Conversion Functions
71
72
Essential functions for converting markdown text and files to HTML, with support for various output formats and processing options.
73
74
```python { .api }
75
def markdown(
76
text: str,
77
html4tags: bool = False,
78
tab_width: int = 4,
79
safe_mode: Optional[Literal['replace', 'escape']] = None,
80
extras: Optional[Union[list[str], dict[str, Any]]] = None,
81
link_patterns: Optional[Iterable[tuple[re.Pattern, Union[str, Callable[[re.Match], str]]]]] = None,
82
footnote_title: Optional[str] = None,
83
footnote_return_symbol: Optional[str] = None,
84
use_file_vars: bool = False,
85
cli: bool = False
86
) -> UnicodeWithAttrs: ...
87
88
def markdown_path(
89
path: str,
90
encoding: str = "utf-8",
91
html4tags: bool = False,
92
tab_width: int = 4,
93
safe_mode: Optional[Literal['replace', 'escape']] = None,
94
extras: Optional[Union[list[str], dict[str, Any]]] = None,
95
link_patterns: Optional[Iterable[tuple[re.Pattern, Union[str, Callable[[re.Match], str]]]]] = None,
96
footnote_title: Optional[str] = None,
97
footnote_return_symbol: Optional[str] = None,
98
use_file_vars: bool = False
99
) -> UnicodeWithAttrs: ...
100
```
101
102
[Core Conversion](./core-conversion.md)
103
104
### Processor Classes
105
106
Reusable markdown processor classes for efficient batch processing and advanced configuration.
107
108
```python { .api }
109
class Markdown:
110
def __init__(
111
self,
112
html4tags: bool = False,
113
tab_width: int = 4,
114
safe_mode: Optional[Literal['replace', 'escape']] = None,
115
extras: Optional[Union[list[str], dict[str, Any]]] = None,
116
link_patterns: Optional[Iterable[tuple[re.Pattern, Union[str, Callable[[re.Match], str]]]]] = None,
117
footnote_title: Optional[str] = None,
118
footnote_return_symbol: Optional[str] = None,
119
use_file_vars: bool = False,
120
cli: bool = False
121
): ...
122
123
def convert(self, text: str) -> UnicodeWithAttrs: ...
124
125
def reset(self) -> None: ...
126
127
class MarkdownWithExtras(Markdown):
128
# Pre-configured with: footnotes, fenced-code-blocks
129
pass
130
```
131
132
[Processor Classes](./processor-classes.md)
133
134
### Text Processing Extras
135
136
Extensions that modify how text elements are processed, including line breaks, emphasis handling, and typography enhancements.
137
138
```python { .api }
139
# Key extras: breaks, code-friendly, middle-word-em, smarty-pants, strike, underline
140
extras = ["breaks", "smarty-pants", "strike"]
141
html = markdown2.markdown(text, extras=extras)
142
```
143
144
[Text Processing Extras](./text-processing-extras.md)
145
146
### Code and Syntax Extras
147
148
Extensions for enhanced code block processing, syntax highlighting, and developer-friendly features.
149
150
```python { .api }
151
# Key extras: fenced-code-blocks, highlightjs-lang, pyshell
152
extras = ["fenced-code-blocks", "code-friendly"]
153
html = markdown2.markdown(code_text, extras=extras)
154
```
155
156
[Code and Syntax Extras](./code-syntax-extras.md)
157
158
### Link and Reference Extras
159
160
Extensions for advanced link processing, auto-linking, and reference management.
161
162
```python { .api }
163
# Key extras: link-patterns, link-shortrefs, markdown-file-links, nofollow
164
link_patterns = [(re.compile(r'bug #(\d+)'), r'http://bugs.example.com/\1')]
165
extras = {"link-patterns": link_patterns}
166
html = markdown2.markdown(text, extras=extras)
167
```
168
169
[Link and Reference Extras](./link-reference-extras.md)
170
171
### Structure and Layout Extras
172
173
Extensions for enhanced document structure including tables, footnotes, headers, and table of contents generation.
174
175
```python { .api }
176
# Key extras: tables, footnotes, header-ids, toc, html-classes
177
extras = ["tables", "footnotes", "header-ids", "toc"]
178
html = markdown2.markdown(text, extras=extras)
179
# Access TOC: html.toc_html
180
```
181
182
[Structure and Layout Extras](./structure-layout-extras.md)
183
184
### Special Content Extras
185
186
Extensions for specialized content types including mathematical expressions, diagrams, and interactive elements.
187
188
```python { .api }
189
# Key extras: latex, mermaid, wavedrom, spoiler, admonitions, alerts
190
extras = ["latex", "mermaid", "admonitions"]
191
html = markdown2.markdown(content, extras=extras)
192
```
193
194
[Special Content Extras](./special-content-extras.md)
195
196
## Types
197
198
```python { .api }
199
class UnicodeWithAttrs(str):
200
"""Enhanced string return type with optional attributes."""
201
metadata: Optional[dict[str, str]] # From 'metadata' extra
202
toc_html: Optional[str] # From 'toc' extra
203
204
class MarkdownError(Exception):
205
"""Base exception for markdown processing errors."""
206
pass
207
208
# Type aliases
209
SafeMode = Literal['replace', 'escape']
210
ExtrasDict = dict[str, Any]
211
ExtrasParam = Union[list[str], ExtrasDict]
212
LinkPatterns = Iterable[tuple[re.Pattern, Union[str, Callable[[re.Match], str]]]]
213
```
214
215
## Constants
216
217
```python { .api }
218
__version__: str # Package version (e.g., "2.5.4")
219
__version_info__: tuple[int, int, int] # Version tuple (e.g., (2, 5, 4))
220
__author__: str # "Trent Mick"
221
DEFAULT_TAB_WIDTH: int # 4
222
```
223
224
## Command Line Interface
225
226
```python { .api }
227
def main(argv: Optional[list[str]] = None) -> None:
228
"""CLI entry point for markdown2 command."""
229
pass
230
```
231
232
The package provides a `markdown2` console script when installed via pip.
233
234
**Basic Usage:**
235
236
```bash
237
# Convert from file to stdout
238
markdown2 document.md
239
240
# Convert from stdin
241
echo "**bold text**" | markdown2
242
243
# Convert to file
244
markdown2 document.md --output document.html
245
246
# Convert multiple files
247
markdown2 doc1.md doc2.md doc3.md
248
```
249
250
**Command Line Options:**
251
252
```bash
253
markdown2 [options] [files...]
254
255
Options:
256
--version Show version and exit
257
-v, --verbose More verbose output
258
--encoding ENCODING Specify encoding of text content (default: utf-8)
259
--html4tags Use HTML 4 style for empty element tags
260
-s MODE, --safe MODE Sanitize literal HTML ('escape' or 'replace')
261
-x EXTRA, --extras EXTRA
262
Turn on specific extras (can be used multiple times)
263
--use-file-vars Look for Emacs-style file variables to enable extras
264
--link-patterns-file FILE
265
Path to a link patterns file
266
--output FILE Output to file instead of stdout
267
--self-test Run internal self-tests
268
--compare Run against Markdown.pl for testing
269
```
270
271
**Examples with Extras:**
272
273
```bash
274
# Enable multiple extras
275
markdown2 -x fenced-code-blocks -x tables -x footnotes document.md
276
277
# With output file
278
markdown2 --extras fenced-code-blocks --extras tables document.md --output doc.html
279
280
# Safe mode with HTML escaping
281
markdown2 --safe escape document.md
282
283
# Custom encoding
284
markdown2 --encoding latin-1 document.md
285
```