MyST-Parser 5.0.0

Release Date: 2026-01-15

This release significantly bumps the supported versions of core dependencies:

‼️ Breaking Changes

This release updates the minimum supported versions:

• Python: >=3.11 (dropped Python 3.10, tests up to 3.14)
• Sphinx: >=8,<10 (dropped Sphinx 7, added Sphinx 9)
• Docutils: >=0.20,<0.23 (dropped docutils 0.19, added docutils 0.22)
• markdown-it-py: ~=4.0 (upgraded from v3)

⬆️ Dependency Upgrades

• ⬆️ Upgrade to markdown-it-py v4 by @chrisjsewell in #1060
• ⬆️ Drop Python 3.10 and Sphinx 7 by @chrisjsewell in #1059
• ⬆️ Drop docutils 0.19 by @chrisjsewell in #1061
• ⬆️ Add support for Python 3.14 by @chrisjsewell in #1075
• ⬆️ Support Sphinx v9 by @chrisjsewell in #1076
• ⬆️ Allow docutils 0.22 by @chrisjsewell in #1084

👌 Improvements

• 👌 Improve generation of meta nodes by @AA-Turner in #1080

📚 Documentation

• 📚 Fix typo in tables.md by @electricalgorithm in #1034
• 📚 Fix minor typo in cross-referencing.md by @krassowski in #1036

🔧 Internal / Maintenance

• 🔧 Update pre-commit by @chrisjsewell in #1058
• 🔧 Add AGENTS.md by @chrisjsewell in #1083

Full Changelog: v4.0.1...v5.0.0

What's Changed

Upgraded dependencies

• ⬆️ Add support for Python 3.12 by @hugovk in #848
• ⬆️ Update docutils requirement from >=0.16,<0.21 to >=0.18,<0.22 by @chrisjsewell in #916

New features

• ✨ Allow for use of the line-block directive by @chrisjsewell in #900
• ✨ Emits sphinx include-read event by @sumezulike in #887

Improvements

• 👌 Nested parse attribution in attr_block by @chrisjsewell in #831
• 👌 Directive option parsing by @chrisjsewell in #796
• 👌 Improve directive parsing warnings by @chrisjsewell in #893
• 👌 Allow for opening external links in new tabs (#856) by @marjus45 in #857

Internal

• 🔧 Replace black, isort, pyupgrade with ruff formatter by @chrisjsewell in #833
• 🔧 remove redundant mypy config by @danieleades in #866
• 🔧 Add additional Ruff lints (and fix issues) by @danieleades in #862
• 🔧 mypy- disallow 'any generics' by @danieleades in #865
• 🔧 Fix docutils deprecation in option parsing by @agoose77 in #842

Documentation

• 📚 Fix a broken link in configuration.md by @zupo in #907
• 📚 Add linkify dependency to contributing docs. by @jhcole in #792
• 📚 Fix the double used in docs/syntax/math.md by @ice-tong in #810
• 📚 Also add linkify to pip install command in README by @n-peugnet in #851
• 📚 Fix the code section title in live preview by @BoboTiG in #875
• 📚 Fix admonition example by @72757373656c6c in #904
• 📚 Fix url for jupyter book gallery by @72757373656c6c in #905
• 📚 Update theme version by @chrisjsewell in #918
• 📚 Fix typo by @blakeNaccarato in #911
• 📚 Fix architecture typo (#855) by @72757373656c6c in #910

New Contributors

• @jhcole made their first contribution in #792
• @ice-tong made their first contribution in #810
• @agoose77 made their first contribution in #842
• @hugovk made their first contribution in #848
• @BoboTiG made their first contribution in #875
• @danieleades made their first contribution in #866
• @marjus45 made their first contribution in #857
• @sumezulike made their first contribution in #887
• @72757373656c6c made their first contribution in #904
• @zupo made their first contribution in #907
• @blakeNaccarato made their first contribution in #911

Full Changelog: v2.0.0...v3.0.0

This release primarily updates core myst-parser dependencies,
with some minor changes to parsing behaviour:

• ⬆️ UPGRADE: markdown-it-py to v3 (#773)

  • This is mainly a non-breaking change, fixing some edge cases in parsing
  • See: https://github.com/executablebooks/markdown-it-py/releases/tag/v3.0.0
    and https://github.com/executablebooks/mdit-py-plugins/releases/tag/v0.4.0

• ⬆️ UPGRADE: linkify-it-py to v2 (https://github.com/executablebooks/MyST-Parser/675)

  • Also fixes some edge cases in parsing
  • See: https://github.com/tsutsu3/linkify-it-py/blob/main/CHANGELOG.md

• ⬆️ UPGRADE: Add support for docutils v0.20 (https://github.com/executablebooks/MyST-Parser/775)

  • No significant changes, see https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-20-2023-05-04

• ⬆️ UPGRADE: Add support for sphinx v7, and remove v5 support (https://github.com/executablebooks/MyST-Parser/776)

  • No significant changes, see https://www.sphinx-doc.org/en/master/changes.html

• ⬆️ UPGRADE: Remove Python 3.7 support and add testing for Python 3.11 (https://github.com/executablebooks/MyST-Parser/772)

• 👌 Improve default slug generation for heading anchors, thanks to @Cimbali (https://github.com/executablebooks/MyST-Parser/777)

  • This change makes the slug generation closer to GitHub, in that, starting/ending whitespace will not be stripped.
    For example, # ` a` b `c ` will now correctly create the slug -a-b-c- and not a-b-c

• 👌 IMPROVE: Substitution extension (https://github.com/executablebooks/MyST-Parser/777)

  • Allow any value type (including dict, list, datetime) and emit a myst.substitution warning for errors in resolving the substitution content.

• 🧪 Introduce a gate/check GHA job, thanks to @webknjaz (https://github.com/executablebooks/MyST-Parser/635)

Full Changelog: v1.0.0...v2.0.0

🎉 MyST-Parser 1.0.0 🎉

This changes absolutely nothing in the code, or about the maintenance/release policy of this project.
But it does feel about time 😄

What's Changed

• ✨ NEW: Add myst_fence_as_directive config by @chrisjsewell in #742

Setting the following config, for example:

extensions = ["myst_parser", "sphinxcontrib.mermaid"]
myst_fence_as_directive = ["mermaid"]
# optional to use directive options
myst_enable_extensions = ["attrs_block"]

allows for one to write:

{caption="My caption"}
{alt="HTML alt" align=center}
```mermaid
graph LR
a --> b
```

and have interoperable rendering with tools like GitHub.

• 📚 Fix the sphinx-design example by @recfab in #738
• 📚 Add html_last_updated_fmt = "" to conf.py by @jeanas in #691

New Contributors

• @recfab made their first contribution in #738

Full Changelog: v0.19.1...v0.19.2

This release brings a number of exciting new features, improvements, and upgrades 🎉
https://myst-parser.readthedocs.io

• 📚 Rewritten documentation, with a clearer structure, many more examples, rich hover tips, and a new live preview page (powered by pyscript)
  • The code base API is also now fully documented by https://sphinx-autodoc2.readthedocs.io/, which even allows for MyST docstrings!
• ⬆️ Add Sphinx 6 support
• 📄 Extended docutils (single-page) support
• 🔗 Extended Markdown links, including intersphinx support, e.g. [text](inv:name#target)
• {} New attributes syntax, to extend common Markdown syntaxes, e.g. ![image](image.png){#id .class width=100px}

For a full list of changes, see: https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md

Happy parsing! 🤖
Executable books team