or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-parsing.mddirectives.mdindex.mdparsing.mdplugins.mdrenderers.mdutilities.md
tile.json

tessl/pypi-mistune

A sane and fast Markdown parser with useful plugins and renderers

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/mistune@3.1.x

To install, run

npx @tessl/cli install tessl/pypi-mistune@3.1.0

index.mddocs/

Mistune

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.

Package Information

  • Package Name: mistune
  • Language: Python
  • Installation: pip install mistune
  • Version: 3.1.4
  • Homepage: https://mistune.lepture.com/

Core Imports

import mistune

Common patterns for creating parsers:

from mistune import create_markdown, HTMLRenderer, Markdown

Basic Usage

import mistune

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

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

# Create custom parser with specific configuration
md = mistune.create_markdown(
    escape=False,
    renderer='html', 
    plugins=['table', 'footnotes', 'strikethrough']
)
result = md('~~deleted text~~')

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

Architecture

Mistune follows a modular architecture with clear separation of concerns:

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

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

Capabilities

Core Parsing

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

def create_markdown(
    escape: bool = True,
    hard_wrap: bool = False, 
    renderer: Optional[RendererRef] = "html",
    plugins: Optional[Iterable[PluginRef]] = None
) -> Markdown

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

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

class Markdown:
    def __init__(
        self,
        renderer: Optional[BaseRenderer] = None,
        block: Optional[BlockParser] = None,
        inline: Optional[InlineParser] = None,
        plugins: Optional[Iterable[Plugin]] = None
    )
    def __call__(self, text: str) -> Union[str, List[Dict[str, Any]]]
    def parse(self, text: str) -> Tuple[Union[str, List[Dict[str, Any]]], BlockState]

Core Parsing

Renderers

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

class HTMLRenderer(BaseRenderer):
    def __init__(self, escape: bool = True, allow_harmful_protocols: Optional[bool] = None)

class RSTRenderer(BaseRenderer):
    def __init__(self)

class MarkdownRenderer(BaseRenderer):
    def __init__(self)

class BaseRenderer:
    def render_tokens(self, tokens: List[Dict[str, Any]], state: BlockState) -> str
    def render_token(self, token: Dict[str, Any], state: BlockState) -> str

Renderers

Plugin System

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.

class Plugin(Protocol):
    def __call__(self, md: Markdown) -> None

def import_plugin(name: PluginRef) -> Plugin

# Built-in plugins
PluginRef = Union[str, Plugin]  # "table", "footnotes", "strikethrough", etc.

Plugin System

Block and Inline Parsing

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

class BlockParser(Parser[BlockState]):
    def __init__(self, ...)
    def parse(self, text: str, state: BlockState) -> None

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

class BlockState:
    src: str
    tokens: List[Dict[str, Any]]
    cursor: int
    env: MutableMapping[str, Any]

class InlineState:  
    src: str
    tokens: List[Dict[str, Any]]
    pos: int
    env: MutableMapping[str, Any]

Block and Inline Parsing

Directives System

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.

class DirectivePlugin:
    def __init__(self, ...)
    
class BaseDirective(metaclass=ABCMeta):
    def parse(self, block: BlockParser, m: Match[str], state: BlockState) -> int
    
# Built-in directives: admonition, include, image, figure, toc

Directives System

Utilities and Helpers

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

def escape(s: str, quote: bool = True) -> str
def escape_url(link: str) -> str  
def safe_entity(s: str) -> str
def unikey(s: str) -> str

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

Utilities and Helpers

Types

# Type aliases
RendererRef = Union[Literal["html", "ast"], BaseRenderer]
PluginRef = Union[str, Plugin]

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

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