{"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":"python","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":[{"wrong":"import myst_parser","symbol":"setup","correct":"from myst_parser import setup"}],"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"},{"fix":"Review the `/script.py` file to ensure it contains valid Python syntax and is correctly configured to use the `myst-parser` library, rather than containing malformed Python code or attempting to execute raw MyST markdown as Python.","message":"The test script `/script.py` encountered a `SyntaxError` on line 25 (e.g., `This is some **MyST Markdown** content.`), indicating the script itself contains invalid Python syntax or was executed incorrectly as a Python file.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure MyST Markdown files are processed by `myst-parser` functions (e.g., `parser.parse()` or via Sphinx integration) from within a valid Python script, rather than being executed directly by the Python interpreter.","message":"Attempting to execute a MyST Markdown file directly with the Python interpreter will result in a `SyntaxError`, as MyST Markdown is not valid Python code. MyST-Parser is a library for parsing Markdown within a Python environment, not a standalone interpreter for Markdown files.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'5.0.0':51 'activ':57 'cadenc':59 'commonmark':9,76 'compat':67 'compliant':10 'current':48 'document':74 'docutil':23,39,73 'enabl':13 'extend':8 'extens':43 'featur':70 'focus':65 'format':37 'includ':38 'integr':46 'librari':29 'maintain':55 'mark':16 'markdown':19,33,72 'myst':1,4,15,32 'myst-pars':3 'new':69 'output':36 'pars':31 'parser':2,5,11,75 'per':63 'project':24,54 'provid':26 'python':28 'releas':58 'seamless':45 'sever':61 'sphinx':21,42,71 'structur':17 'text':18 'updat':62 'various':35 'version':49 'write':14 'year':64","created_at":"2026-04-09T03:54:06.740709+00:00","updated_at":"2026-04-16T17:18:31.959064+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"5.1.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://myst-parser.readthedocs.io","github":"https://github.com/executablebooks/MyST-Parser","docs":"https://myst-parser.readthedocs.io","changelog":null,"pypi":"https://pypi.org/project/myst-parser/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-08-27","next_check":"2026-07-30","install_tag":null}}