{"id":1577,"library":"myst-parser","title":"MyST Parser","description":"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.","status":"active","version":"5.0.0","language":"en","source_language":"en","source_url":"https://github.com/executablebooks/MyST-Parser","tags":["sphinx","markdown","docutils","documentation","parser","commonmark"],"install":[{"cmd":"pip install myst-parser","lang":"bash","label":"PyPI"},{"cmd":"conda install -c conda-forge myst-parser","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"Minimum Python version required for MyST-Parser v5.0.0.","package":"python","version":">=3.11"},{"reason":"Required for Sphinx integration.","package":"sphinx","version":">=8,<10"},{"reason":"Core dependency for parsing and rendering.","package":"docutils","version":">=0.20,<0.23"},{"reason":"Underlying CommonMark parser.","package":"markdown-it-py","version":"~=4.0"}],"imports":[{"note":"The primary way to use MyST-Parser is by enabling it as a Sphinx extension in your conf.py file.","symbol":"myst_parser (as Sphinx extension)","correct":"# in conf.py\nextensions = [\n    \"myst_parser\"\n]"},{"note":"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.","symbol":"to_html / to_docutils / to_tokens","correct":"from myst_parser.main import to_html, to_docutils, to_tokens"}],"quickstart":{"code":"# conf.py\nextensions = [\n    \"myst_parser\",\n    \"sphinx.ext.autodoc\"\n]\n\n# Enable common MyST extensions\nmyst_enable_extensions = [\n    \"colon_fence\",\n    \"deflist\",\n    \"fieldlist\",\n    \"html_admonition\",\n    \"html_image\",\n    \"linkify\",\n    \"replacements\",\n    \"smartquotes\",\n    \"strikethrough\",\n    \"substitution\",\n    \"tasklist\"\n]\n\n# index.md\n# MyST Project\n\nThis is some **MyST Markdown** content.\n\n:::{note}\nThis is a MyST admonition.\n:::\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.11 or higher. If you need Python 3.10 support, use `myst-parser<5.0.0`.","message":"MyST-Parser v5.0.0 drops support for Python <3.11. Ensure your environment meets the new minimum requirement.","severity":"breaking","affected_versions":"5.0.0 and later"},{"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).","message":"MyST-Parser v5.0.0 significantly updates minimum Sphinx and Docutils versions. Old versions will not be compatible.","severity":"breaking","affected_versions":"5.0.0 and later"},{"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.","message":"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.","severity":"breaking","affected_versions":"5.0.0 and later"},{"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`.","message":"Versions 4.0.0 also introduced breaking changes to minimum Python, Sphinx, and Docutils requirements.","severity":"breaking","affected_versions":"4.0.0 - 4.x.x"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"0.19.2 and later"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}