MyST Parser

MyST Parser is the reference implementation of MyST Markdown (Markedly Structured Text), a flavor of Markdown extended past plain CommonMark with the directive and role syntax needed for serious technical documentation — admonitions, cross-references, footnotes, math, and Sphinx-style directives — all written in Markdown instead of reStructuredText. It’s built on top of markdown-it-py for CommonMark-compliant parsing and translates the resulting token stream into docutils nodes.

As a Sphinx extension (extensions = ["myst_parser"] in conf.py), it lets projects write .md files that participate fully in the Sphinx build — cross-references, toctrees, and all the Sphinx directives that were previously reStructuredText-only — without abandoning existing reStructuredText content, since both formats can coexist in the same Sphinx project.

What You Get

• An extended CommonMark parser (built on markdown-it-py) supporting directives, roles, footnotes, and math beyond plain Markdown
• A Sphinx extension that lets .md files use the same directives, cross-references, and toctrees as Sphinx’s native reStructuredText
• A docutils bridge (docutils_.py) for using MyST outside of Sphinx, in any docutils-based pipeline
• Coexistence with existing reStructuredText files in the same Sphinx project, for incremental migration
• Configurable syntax extensions (e.g. colon_fence, deflist, linkify) enabled per-project via Sphinx config
• A CLI (myst_parser.cli) for parsing MyST files outside of a full Sphinx build, e.g. for debugging or CI checks

Common Use Cases

• Sphinx-based documentation projects that want to author in Markdown instead of reStructuredText without losing Sphinx features
• Teams migrating existing docs from plain Markdown or reStructuredText to a richer format supporting cross-references and admonitions
• Scientific/technical documentation (e.g. Jupyter Book projects) that need math, footnotes, and citations in Markdown
• Documentation pipelines that need docutils-level output (HTML, LaTeX) from Markdown source without going through Sphinx directly

Under The Hood

Architecture - The myst_parser package layers three concerns: parsers/ and mdit_to_docutils/ implement the actual CommonMark-to-extended-Markdown parsing (via markdown-it-py) and its conversion into docutils document-tree nodes, sphinx_.py and sphinx_ext/ wire that parser into Sphinx’s extension API (registering it as a source parser and adding Sphinx-specific directives/roles), and docutils_.py provides a standalone docutils reader for non-Sphinx use; config/ centralizes the many toggleable syntax extensions. Tech Stack - Python 3.11+, MIT licensed, built on markdown-it-py for CommonMark tokenizing and docutils/sphinx for the document-tree and build-system integration; distributed via flit_core rather than setuptools. Code Quality - The tests/ directory contains at least 15 test_*.py modules covering parser output and Sphinx integration, the project publishes coverage via Codecov, and 566 total commits across 67 tagged releases over more than five years indicate a mature, continuously maintained codebase used as the de facto standard for Markdown-in-Sphinx tooling. API Design - For end users the entire integration surface is a single conf.py line (extensions = ["myst_parser"]), after which existing Sphinx knowledge (directives, roles, toctrees) transfers almost unchanged to Markdown files; going deeper into custom syntax extensions or the standalone docutils API requires reading the more extensive configuration docs, but the common path stays low-friction.