myst-parser

What it is and what it does

MyST-Parser is a Markdown parser and Sphinx extension that lets you write technical documentation in Markdown instead of reStructuredText. It implements an extended CommonMark dialect designed for flexibility and extensibility, built on markdown-it-py and integrated with Sphinx's rendering pipeline. The package acts as a bridge between Markdown's simplicity and Sphinx's documentation capabilities, parsing .md files through docutils and Jinja2 templating to produce the same output as native Sphinx sources.

You install it as a Sphinx extension by adding it to your conf.py, then write .md files in your documentation tree. It handles YAML frontmatter, code directives, cross-references, and other technical markup common in API docs and tutorials. The parser depends on markdown-it-py for tokenization, mdit-py-plugins for extended syntax, and pyyaml for metadata extraction.

Use it for:

• Convert an existing reStructuredText Sphinx project to Markdown without rewriting all source files.
• Author technical documentation in Markdown while keeping Sphinx's build system and theme infrastructure.
• Mix Markdown and reStructuredText sources in a single Sphinx project for gradual migration.
• Use Markdown's simpler syntax for tutorials and guides while maintaining cross-references and code examples.
• Extend Markdown with Sphinx directives (like :doc:, :ref:) for linking and API documentation.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

MyST-Parser extends CommonMark-compliant Markdown with syntax for technical documentation, integrating with Sphinx to render MyST Markdown files as part of documentation builds.

Yes. MyST-Parser is actively maintained, has no known vulnerabilities, installs with low friction, and solves a real problem for teams wanting Markdown in Sphinx. It's a mature Beta-status tool (in production use since 2020) with broad Python support. Install it if you want to author Sphinx docs in Markdown or migrate an existing project away from reStructuredText.

Install

myst-parser on PyPI

pip install myst-parser

uv add myst-parser

poetry add myst-parser

Installing myst-parser

Before you install

Low friction installation with a pure-Python wheel. Actively maintained (last commit 2026-08-10, 93 days since release), supports current Python versions (3.11–3.14), and has a stable foundation with 886 repository stars.

License in practice

Licensed under MIT (permissive), so you can use, modify, and distribute the package freely with minimal restrictions.

Quickstart

pip install myst-parser

# In Sphinx conf.py:
extensions = ["myst_parser"]

# Then write .md files in your Sphinx project

Requires Python 3.11 or later and an existing Sphinx documentation project.

Verify before relying

• Whether MyST syntax extensions (e.g., for cross-references, code directives) are documented and stable for production use.
• Performance characteristics when parsing large or deeply nested Markdown documents.
• Compatibility matrix with specific Sphinx versions beyond the classifier range.

Package facts

Evidence: myst_parser-5.1.0-py3-none-any.whl

Keywords: markdown, lexer, parser, development, docutils, sphinx

Tags

More Python Modules packages