Markdown2

2.5.5 · active · verified Thu Apr 09

Markdown2 is a fast and complete Python implementation of Markdown, designed to closely match the behavior of the original Perl-implemented Markdown.pl. It offers a core Markdown parser and numerous extensions, known as 'extras,' for enhanced functionality like syntax highlighting, tables, and header IDs. The library is actively maintained with periodic releases and currently supports Python 3.9 and newer.

Warnings

deprecated The 'code-color' extra (for Pygments-based syntax highlighting) is deprecated. Use the 'fenced-code-blocks' extra instead, which offers better and more modern syntax highlighting capabilities.
Fix: Replace `extras=['code-color']` with `extras=['fenced-code-blocks']` in your `markdown2.markdown()` call or `Markdown` object initialization. Ensure Pygments is installed for syntax highlighting: `pip install Pygments`.
gotcha Markdown2 directly outputs HTML, including any raw HTML present in the input Markdown. If processing untrusted user-generated content, ensure you sanitize the resulting HTML with a dedicated HTML sanitizer (e.g., 'Bleach') to prevent Cross-Site Scripting (XSS) vulnerabilities.
Fix: Always pass the HTML output from `markdown2.markdown()` through an HTML sanitization library like 'Bleach' before rendering it in a web browser, especially when dealing with untrusted input. Example: `import bleach; sanitized_html = bleach.clean(html_output)`.
gotcha Inconsistent or incorrect Markdown syntax can lead to unexpected rendering. Common pitfalls include missing blank lines between paragraphs or block-level elements, lack of space after heading hashes (`#`), or incorrect indentation for lists and code blocks.
Fix: Adhere strictly to Markdown syntax guidelines. Ensure blank lines separate block-level elements. Always put a space after `#` for headings. Maintain consistent indentation (usually 2 or 4 spaces) for lists and indented code blocks. Tools like Markdown linters can help catch these issues.

Install

pip install markdown2 Install stable version
pip install markdown2[all] Install with all optional dependencies (e.g., Pygments for code highlighting)

Imports

markdown
```
from markdown2 import markdown
```
The primary function for converting Markdown text to HTML.
Markdown
```
from markdown2 import Markdown
```
The class-based interface, useful for configuring a Markdown converter with specific extras or settings.

Quickstart

This quickstart demonstrates basic Markdown conversion using the `markdown()` function and how to enable 'extras' (extensions) for enhanced features like fenced code blocks. It also shows the class-based `Markdown` API for more persistent configuration.

import markdown2

markdown_text = """
# Hello, Markdown2!

This is a paragraph with *emphasis* and **strong emphasis**.

- List item 1
- List item 2

```python
print('Hello from a code block!')
```

Checkout the [Markdown2 GitHub page](https://github.com/trentm/python-markdown2).
"""

# Basic conversion
html = markdown2.markdown(markdown_text)
print("--- Basic Conversion ---")
print(html)

# Conversion with an extra (e.g., 'fenced-code-blocks' for syntax highlighting)
html_with_extras = markdown2.markdown(markdown_text, extras=["fenced-code-blocks", "footnotes"])
print("\n--- Conversion with Extras ---")
print(html_with_extras)

# Using the class-based API
markdowner = markdown2.Markdown(extras=["tables", "header-ids"])
html_from_class = markdowner.convert("| Header 1 | Header 2 |\n|----------|----------|\n| Cell 1   | Cell 2   |\n\n### My Section")
print("\n--- Class-based Conversion with Extras ---")
print(html_from_class)

view raw JSON →