or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdconfiguration.mdcore-parsing.mdindex.mdlink-processing.mdrendering.mdsyntax-tree.mdtoken-system.md
tile.json

tessl/pypi-markdown-it-py

Python port of markdown-it providing CommonMark-compliant markdown parsing with configurable syntax and pluggable architecture

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/markdown-it-py@4.0.x

To install, run

npx @tessl/cli install tessl/pypi-markdown-it-py@4.0.0

index.mddocs/

markdown-it-py

A Python port of the popular markdown-it JavaScript library, providing CommonMark-compliant markdown parsing with configurable syntax and pluggable architecture. Offers high performance, security features, and extensibility for markdown processing in Python applications.

Package Information

  • Package Name: markdown-it-py
  • Language: Python
  • Installation: pip install markdown-it-py[plugins]
  • Optional Dependencies:
    • pip install markdown-it-py[linkify] for URL autoconversion
    • pip install markdown-it-py[plugins] for syntax extensions

Core Imports

from markdown_it import MarkdownIt

For advanced usage:

from markdown_it import MarkdownIt
from markdown_it.token import Token
from markdown_it.tree import SyntaxTreeNode
from markdown_it.renderer import RendererHTML

Basic Usage

from markdown_it import MarkdownIt

# Basic markdown parsing
md = MarkdownIt()
html = md.render("# Hello World\n\nThis is **bold** text.")
print(html)
# Output: <h1>Hello World</h1>\n<p>This is <strong>bold</strong> text.</p>\n

# Using presets and enabling features
md = (
    MarkdownIt('commonmark', {'breaks': True, 'html': True})
    .enable(['table', 'strikethrough'])
)

markdown_text = """
# Table Example

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

~~Strikethrough text~~
"""

html = md.render(markdown_text)
print(html)

# Parse to tokens for advanced processing
tokens = md.parse(markdown_text)
for token in tokens:
    print(f"{token.type}: {token.tag}")

Architecture

markdown-it-py follows a multi-stage parsing architecture:

  • MarkdownIt: Main parser class coordinating all components
  • ParserCore: Orchestrates the parsing pipeline through rule chains
  • ParserBlock: Processes block-level elements (paragraphs, headers, lists)
  • ParserInline: Handles inline elements (emphasis, links, code spans)
  • Renderer: Converts parsed tokens to output format (HTML by default)
  • Token: Represents parsed markdown elements with metadata
  • Ruler: Manages parsing rules and their execution order

This design enables complete customization of parsing behavior through rule modification, custom renderers, and plugin integration.

Capabilities

Core Parsing and Rendering

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

class MarkdownIt:
    def render(self, src: str, env: dict = None) -> str: ...
    def parse(self, src: str, env: dict = None) -> list[Token]: ...
    def renderInline(self, src: str, env: dict = None) -> str: ...
    def parseInline(self, src: str, env: dict = None) -> list[Token]: ...

Core Parsing

Configuration and Presets

Parser configuration system with built-in presets (commonmark, default, zero, gfm-like) and rule management for customizing parsing behavior.

class MarkdownIt:
    def configure(self, presets: str | dict, options_update: dict = None) -> MarkdownIt: ...
    def enable(self, names: str | list[str], ignoreInvalid: bool = False) -> MarkdownIt: ...
    def disable(self, names: str | list[str], ignoreInvalid: bool = False) -> MarkdownIt: ...
    def use(self, plugin: callable, *params, **options) -> MarkdownIt: ...

Configuration

Token System

Structured representation of parsed markdown elements with metadata, attributes, and hierarchical relationships for advanced processing and custom rendering.

class Token:
    type: str
    tag: str
    attrs: dict[str, str | int | float]
    content: str
    children: list[Token] | None
    def as_dict(self) -> dict: ...
    def copy(self, **changes) -> Token: ...

Token System

Rendering and Output

HTML rendering system with customizable render rules and support for custom renderers to generate different output formats.

class RendererHTML:
    def render(self, tokens: list[Token], options: dict, env: dict) -> str: ...
    def renderInline(self, tokens: list[Token], options: dict, env: dict) -> str: ...
    def add_render_rule(self, name: str, function: callable, fmt: str = "html") -> None: ...

Rendering

Syntax Tree Processing

Tree representation utilities for converting linear token streams into hierarchical structures for advanced document analysis and manipulation.

class SyntaxTreeNode:
    def __init__(self, tokens: list[Token] = (), *, create_root: bool = True): ...
    def to_pretty(self, *, indent: int = 2, show_text: bool = False) -> str: ...
    def to_tokens(self) -> list[Token]: ...

Syntax Tree

Link Processing and Security

URL validation, normalization, and link processing utilities with built-in security features to prevent XSS attacks.

class MarkdownIt:
    def validateLink(self, url: str) -> bool: ...
    def normalizeLink(self, url: str) -> str: ...
    def normalizeLinkText(self, link: str) -> str: ...

Link Processing

Command Line Interface

Command-line tools for converting markdown files to HTML with batch processing and interactive modes.

def main(args: list[str] = None) -> int: ...
def convert(filenames: list[str]) -> None: ...
def interactive() -> None: ...

CLI

Types

# Type aliases and protocols
EnvType = dict[str, Any]  # Environment sandbox for parsing

class OptionsType(TypedDict):
    maxNesting: int                # Internal protection, recursion limit
    html: bool                     # Enable HTML tags in source
    linkify: bool                  # Enable autoconversion of URL-like texts to links
    typographer: bool              # Enable smartquotes and replacements
    quotes: str                    # Quote characters
    xhtmlOut: bool                 # Use '/' to close single tags (<br />)
    breaks: bool                   # Convert newlines in paragraphs into <br>
    langPrefix: str                # CSS language prefix for fenced blocks
    highlight: callable | None     # Highlighter function: (content, lang, attrs) -> str
    store_labels: bool             # Store link labels in token metadata (optional)

class PresetType(TypedDict):
    options: OptionsType
    components: dict[str, dict[str, list[str]]]  # Component rules configuration

class OptionsDict(dict):
    """Options dictionary with attribute access to core configuration options."""
    
    # Properties for each option with getters/setters
    maxNesting: int
    html: bool
    linkify: bool
    typographer: bool
    quotes: str
    xhtmlOut: bool
    breaks: bool
    langPrefix: str
    highlight: callable | None

class RendererProtocol(Protocol):
    __output__: str
    def render(self, tokens: list[Token], options: OptionsDict, env: EnvType) -> Any: ...