MyST Parser

5.0.0 · active · verified Thu Apr 09

MyST-Parser is an extended CommonMark compliant parser that enables writing MyST (Markedly Structured Text) Markdown in Sphinx and Docutils projects. It provides a Python library for parsing MyST Markdown to various output formats, including docutils, and a Sphinx extension for seamless integration. The current version is 5.0.0, and the project maintains an active release cadence, with several updates per year, focusing on compatibility and new features.

Warnings

breaking MyST-Parser v5.0.0 drops support for Python <3.11. Ensure your environment meets the new minimum requirement.
Fix: Upgrade your Python environment to 3.11 or higher. If you need Python 3.10 support, use `myst-parser<5.0.0`.
breaking MyST-Parser v5.0.0 significantly updates minimum Sphinx and Docutils versions. Old versions will not be compatible.
Fix: Upgrade Sphinx to `>=8,<10` and Docutils to `>=0.20,<0.23`. If using an older Sphinx/Docutils, you must pin `myst-parser` to a compatible version (e.g., `<5.0.0` for Sphinx 7, Docutils 0.19).
breaking The underlying `markdown-it-py` parser was upgraded to `~=4.0` in v5.0.0 (from v3 in v2.0.0), potentially introducing subtle parsing behavior changes or requiring plugin updates.
Fix: Review your MyST markdown for any edge cases, especially if you rely on specific `markdown-it-py` plugins or custom parser logic. Consult `markdown-it-py` v4 release notes for details.
breaking Versions 4.0.0 also introduced breaking changes to minimum Python, Sphinx, and Docutils requirements.
Fix: Ensure Python `>=3.10`, Sphinx `>=7,<9`, and Docutils `>=0.19,<0.22` are installed when using `myst-parser>=4.0.0,<5.0.0`.
gotcha Direct API functions like `to_html` or `to_docutils` are mainly for testing/development. For full Sphinx-specific features (e.g., cross-references, custom directives), use the Sphinx build process or explicitly load Sphinx-specific renderers with `in_sphinx_env`.
Fix: For comprehensive documentation generation, integrate MyST-Parser via the Sphinx `extensions` mechanism. For standalone parsing with Sphinx roles/directives, configure `in_sphinx_env=True` when initializing renderers.
gotcha To use fenced code blocks as Sphinx directives (e.g., for Mermaid diagrams or other renderers), you must explicitly enable `myst_fence_as_directive` in your `conf.py`.
Fix: Add `myst_fence_as_directive = ["directive_name"]` to your `conf.py`, where `directive_name` is the name of the directive (e.g., `mermaid`) you want to associate with fenced code blocks.

Install

pip install myst-parser PyPI
conda install -c conda-forge myst-parser Conda

Imports

myst_parser (as Sphinx extension)
```
# in conf.py
extensions = [
    "myst_parser"
]
```
The primary way to use MyST-Parser is by enabling it as a Sphinx extension in your conf.py file.
to_html / to_docutils / to_tokens
```
from myst_parser.main import to_html, to_docutils, to_tokens
```
These functions provide direct Python API access for parsing MyST Markdown to different formats (HTML, Docutils AST, raw tokens), mainly for testing or programmatic use outside of a Sphinx build.

Quickstart

To quickly get started, add `myst_parser` to your Sphinx `conf.py` extensions list. This enables parsing of `.md` files as MyST Markdown. You can also configure various MyST extensions like `colon_fence` or `admonition` via `myst_enable_extensions` in `conf.py` or through frontmatter in individual documents.

# conf.py
extensions = [
    "myst_parser",
    "sphinx.ext.autodoc"
]

# Enable common MyST extensions
myst_enable_extensions = [
    "colon_fence",
    "deflist",
    "fieldlist",
    "html_admonition",
    "html_image",
    "linkify",
    "replacements",
    "smartquotes",
    "strikethrough",
    "substitution",
    "tasklist"
]

# index.md
# MyST Project

This is some **MyST Markdown** content.

:::{note}
This is a MyST admonition.
:::

view raw JSON →