# MyST-Parser: CommonMark Markdown that compiles to docutils and runs inside Sphinx > MyST-Parser is the reference implementation of MyST Markdown, an extended CommonMark-compliant parser built on markdown-it-py that targets docutils and ships as a Sphinx extension, so technical documentation can be written in Markdown and built with the Sphinx toolchain. It suits documentation teams moving from reStructuredText and teams that want one Markdown dialect with Sphinx features available. **executablebooks/MyST-Parser** — An extended commonmark compliant parser, with bridges to docutils/sphinx - Repository: https://github.com/executablebooks/MyST-Parser - Website: https://myst-parser.readthedocs.io - Stars: 898 · Forks: 245 - Language: Python - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/executablebooks-myst-parser ## Markdown that ends up in the docutils pipeline MyST is described as a rich and extensible flavor of Markdown meant for technical documentation and publishing, and MyST-Parser is the reference implementation of that flavor along with a collection of tools for working with MyST in Python and Sphinx. The mechanism is what distinguishes this from a Markdown library that just emits HTML. The parser is an extended CommonMark-compliant parser built on markdown-it-py, and its output target is docutils, the document tree library that Sphinx is built on. So a MyST document is not converted to HTML and then handed to Sphinx. It is parsed into docutils nodes, which is the same representation a reStructuredText file produces, and the rest of the Sphinx toolchain cannot tell the difference. That is the whole point of the project, and it explains why the description mentions bridges to docutils and Sphinx. Writing documentation in Markdown is a preference many teams have, and the usual objection is that Markdown extensions are ad hoc: a footnote syntax here, a directive syntax there, none of it standard, and a documentation build that depends on a specific parser's quirks. MyST's answer is to extend CommonMark rather than invent a dialect, and to make the extensions land on docutils constructs that Sphinx already understands. The topic list on the repository names the same four things: docutils, markdown-parser, sphinx and sphinx-extension. There is no separate MyST toolchain, no second build system, no alternative rendering path. The output is docutils, and Sphinx renders it. The audience is documentation engineers and technical writers, and the maintainer is named in the package metadata, Chris Sewell, with the project hosted under the executablebooks organisation, which is a group rather than a single employer. ## Installing the parser and enabling it in conf.py Installation is two commands, and the README recommends the Conda route: ```bash conda install -c conda-forge myst-parser ``` or, equivalently through pip: ```bash pip install myst-parser ``` The README also gives the development install, which clones the repository, checks out the master branch and installs the package in editable mode with the extras: ```bash git clone https://github.com/executablebooks/MyST-Parser cd MyST-Parser git checkout master pip install -e .[code_style,linkify,testing,rtd] ``` The four extras are not arbitrary. code_style brings in pre-commit, which matches the .pre-commit-config.yaml at the repository root and the black code style badge in the README. linkify pulls in linkify-it-py, which the pyproject.toml comment identifies as the implementation of the linkify extension, the one that turns bare URLs in text into links. testing and rtd cover the test and documentation builds. Using it in Sphinx is one line. The README says to add extensions = ["myst_parser"] to your conf.py. There is no separate parser configuration step in the visible documentation, which is the point: the extension registers itself and the rest of the build behaves as it would for any other Sphinx project. The repository layout is conventional for a Python package with a documentation build. There is a myst_parser/ directory for the code, tests/, docs/, a pyproject.toml, a tox.ini, a CHANGELOG.md, an AGENTS.md for coding agents, a codecov.yml, a .readthedocs.yml for the hosted documentation, and an example-include.md file that appears to exist as a fixture for the include directive. ## Pinned dependency ranges, and the Python floor they imply The dependency block in pyproject.toml is where the project's real constraints live, and they are worth reading before you install anything into an existing environment. The package requires Python 3.11 or newer, and the classifiers list 3.11, 3.12, 3.13 and 3.14, with both CPython and PyPy listed as implementations. The development status classifier is Development Status :: 4 - Beta, which is a useful calibration of what the maintainer considers the maturity of the package. The runtime dependencies are docutils>=0.20,<0.24, jinja2 with the comment that it is required for substitutions but Sphinx should choose the version, markdown-it-py~=4.2, mdit-py-plugins~=0.6 with a floor of 0.6.1, pyyaml, and sphinx>=8,<10. Two of those are worth pausing on. The docutils range is a bounded window of three minor versions, and the Sphinx range excludes everything below version 8 and everything at version 10 or above. Neither dependency is left open, which is good practice for a library that manipulates document trees, and it is also a real constraint on adoption. If your documentation build pins Sphinx 7, this parser is not a drop-in, and the resolution is a Sphinx upgrade rather than a parser version tweak. The jinja2 entry is worth reading closely too. The comment says it is required for substitutions, but let Sphinx choose the version. That is a deliberate decoupling: MyST needs jinja2 to exist for its substitution feature, but does not want to constrain the version, because Sphinx pins it for the whole build. Pinning it would risk a resolver conflict for every user. The keywords list lexer, parser, docutils, sphinx and markdown, and the topic classifiers are Python Modules and Text Processing, Markup. The build backend is flit_core with a version and description declared as dynamic, so the version comes from the package source rather than a literal in the manifest. ## Where Markdown parsing stops and docutils takes over The extension structure is worth understanding, because it is where the interesting behaviour lives. MyST-Parser is not a single parser. It is a set of rules and plugins that plug into markdown-it-py, the CommonMark parser it depends on. The mdit-py-plugins dependency exists to supply that plugin infrastructure, and the linkify-it-py extra is one concrete example of a MyST extension implemented on top of it. The division of labour is this. markdown-it-py handles the CommonMark core, so anything that is valid CommonMark parses the same way it would in any other CommonMark implementation. On top of that, MyST adds the constructs that technical documentation needs and that CommonMark has no equivalent for: directives, which map onto docutils directives; roles, which map onto docutils roles; and cross-references, which become docutils reference nodes pointing at Sphinx targets. A MyST document can therefore use a Sphinx directive that a plain Markdown parser would have to render as literal text. This is also where the trade-off lives. CommonMark compatibility is a constraint on the extension syntax. A MyST directive is written in a way that has to remain parseable as CommonMark, which shapes the syntax of things like front matter and admonitions. The benefit is that a MyST file still renders in any CommonMark renderer, albeit with some constructs degraded, and the cost is that the extensions cannot be as expressive as a full reStructuredText vocabulary. The second consequence is that the docutils output is a public interface. Anything built on the parsed tree, a Sphinx extension that inspects nodes, a custom directive, a transform, is coupled to how MyST maps its syntax onto docutils nodes. The reference implementation status matters here, because the mapping is what other tools in the ecosystem will have been written against. ## A fast release cadence, a beta classification and no version pinning advice On maintenance, the repository is not archived and the last push was on 2026-10-19, on the master branch. The release history shows a project on a 5.x line with a major version roughly every few months. v5.1.0 came on 2026-05-13, v5.0.0 on 2026-01-15, and v4.0.1 on 2025-02-12. So the releases arrive on a cadence of roughly a few months at most, and a recent push after the last tag means work is continuing between releases. The combination of a 5.x line, major versions arriving that regularly, and the Beta development status classifier means one thing for an adopter: a major version bump is a routine event and not a signal of trouble, but it is also work. The upgrade path in a documentation build is straightforward in principle, since the output is docutils and Sphinx handles the rest, and the CHANGELOG.md at the repository root is where the changes between versions are recorded. The maintenance reality also has a documentation side. The README's Contributing section is one line, welcome all contributions, with a pointer to the contributing guide in the MyST Parser documentation, and the repository carries an AGENTS.md, which is a newer convention for instructing coding agents on a project. One thing the README does not do is give upgrade guidance, and the visible documentation does not say how to migrate a project from one major version to the next. For a package whose whole job is to be a stable layer between authors and a documentation build, that is a gap worth asking about, and the CHANGELOG.md plus the versioned documentation at myst-parser.readthedocs.io are the places to look. The licence is MIT, declared in pyproject.toml as a file reference to the LICENSE at the root of the tree, and the topics on the repository include sphinx-extension, which tells you where the package sits in a build. ## Conclusion MyST-Parser fits a documentation team that wants Markdown authoring with a Sphinx build, especially one that values CommonMark compatibility and the docutils bridges, and the reference implementation plus the Sphinx extension in one repository is the version to build on rather than a reimplementation. It is the wrong choice for a simple static site with no docutils tooling in the loop, where plain Markdown plus a static site generator is less machinery, and it is the wrong choice if you cannot accept a Sphinx extension in your build, because the docutils output is the core of the design. Before you adopt it, confirm the Python version floor, since the package requires Python 3.11 or newer, and check that the docutils and Sphinx version ranges in pyproject.toml match the versions already in your environment, since both are pinned to a range rather than left open. ## FAQ ### How do I install MyST-Parser? The README recommends Conda with `conda install -c conda-forge myst-parser`, or `pip install myst-parser`. For development it clones the repository, checks out master and runs `pip install -e .[code_style,linkify,testing,rtd]`. ### How do I enable MyST Markdown in a Sphinx project? Add `extensions = ["myst_parser"]` to your conf.py, as the README states. The package is a Sphinx extension, and the MyST Parser documentation site is at myst-parser.readthedocs.io. ### What does MyST-Parser depend on? The pyproject.toml lists docutils>=0.20,<0.24, jinja2, markdown-it-py~=4.2, mdit-py-plugins~=0.6, pyyaml and sphinx>=8,<10, and the package requires Python 3.11 or newer. ### Is MyST-Parser CommonMark compliant? The README describes it as an extended CommonMark-compliant parser that uses markdown-it-py, and MyST itself as a flavor of Markdown designed for simplicity, flexibility and extensibility. The extensions are layered on top of the CommonMark core. ### How is MyST-Parser released and maintained? The repository is not archived and the last push was on 2026-10-19. The recent tags are v5.1.0 from 2026-05-13, v5.0.0 from 2026-01-15 and v4.0.1 from 2025-02-12, the package is classified as Development Status :: 4 - Beta, and the licence is MIT. ## Sources - [executablebooks/MyST-Parser on GitHub](https://github.com/executablebooks/MyST-Parser) - [License: MIT](https://github.com/executablebooks/MyST-Parser/blob/master/LICENSE) - [Project website](https://myst-parser.readthedocs.io) - [README](https://github.com/executablebooks/MyST-Parser/blob/master/README.md) - [Releases](https://github.com/executablebooks/MyST-Parser/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/executablebooks-myst-parser