Markdown

Python-Markdown is a pure-Python implementation of John Gruber’s Markdown specification, converting Markdown-formatted text into HTML or XHTML. It ships as both an importable library (markdown.markdown(text)) and a markdown_py command-line tool, and has been the de facto standard Markdown processor in the Python ecosystem for over a decade — used internally by tools like MkDocs, Pelican, and Django’s markdown filters.

The library’s defining architectural choice is its multi-stage, registry-driven pipeline: text passes through preprocessors, a block parser, inline pattern matchers, tree processors, and postprocessors, with an Extension API that can hook into any of those stages via priority-ordered registries. This is what lets the project ship optional syntax (tables, footnotes, table of contents, definition lists, code highlighting, and more) as separate, independently maintainable extensions rather than baking every feature into the core parser.

What You Get

• A markdown.markdown(text) one-line conversion function plus a reusable Markdown class for repeated conversions with shared state
• A five-stage processing pipeline (preprocessors, block parser, inline patterns, tree processors, postprocessors) exposed as public, extensible registries
• An Extension base class and markdown.extensions entry-point group so third-party packages can register new syntax by name
• A large set of first-party extensions bundled in the extra package: tables, footnotes, toc, def_list, attr_list, admonition, fenced_code, codehilite, smarty, sane_lists, wikilinks, and more
• A markdown_py CLI for converting files from the shell without writing any Python
• HTML sanitization via an HtmlStash that protects raw HTML blocks from being mangled by the Markdown parser

Common Use Cases

• Rendering user-authored Markdown (blog posts, comments, docs) to HTML inside a Python web app such as Django or Flask
• Powering static-site generators and documentation tools (MkDocs, Pelican, and similar projects build directly on this library)
• Adding GitHub-flavored features like tables, footnotes, and syntax-highlighted fenced code blocks to Markdown content pipelines
• Building a custom Markdown dialect by writing project-specific Extension subclasses that register new inline or block syntax
• Batch-converting .md files to HTML from the command line via markdown_py

Under The Hood

Architecture The core Markdown class (markdown/core.py) builds five ordered, priority-sorted Registry collections in build_parser() — preprocessors, a block-level BlockParser, inline pattern matchers, tree processors, and postprocessors — and a text conversion simply pushes the input string through each stage in order, ending in a serializers.to_html_string/to_xhtml_string call over the resulting ElementTree. Extensions (markdown/extensions/*.py) are the primary extension point: each subclasses extensions.Extension, implements extendMarkdown(), and registers new processors or patterns into these same registries at a chosen priority, so third-party syntax composes with the core pipeline instead of forking it. This registry-of-registries design is what lets the codebase stay a monolith-per-conversion while remaining highly modular in practice — changing the core Registry class in util.py would ripple through every extension in the repo.