Repository navigation
Releases
v5.2.0
Heading anchors are now stable and documented:
one shared slug implementation with "github", "gitlab" and "docutils" presets,
slugs emitted as real HTML ids, explicit (target)= ids taking priority, and a versioned anchor contract.
Warnings and other tools now get accurate source lines (also inside {include}d files),
docutils 0.23 is supported, inputs that used to abort the build now warn instead,
and many fixes land for references, images, front matter, substitutions and directives;
a new section_ref extension links §1.1-style references to numbered headings.
Nothing is dropped: Python >=3.11, Sphinx >=8,<10 and the markdown-it-py requirement are unchanged,
mdit-py-plugins is raised to ~=0.7 (it was ~=0.6,>=0.6.1),
and the docutils range is widened to >=0.20,<0.24.
Some of these changes can still alter the output of a project that built before, so please read the upgrade notes.
‼️ Upgrade notes
- Heading anchors (#1158, #1168), see docs:
- Duplicate heading slugs now get fixed-base suffixes,
x,x-1,x-2, as on GitHub;
the third and later duplicates used to getx-1-2,x-1-2-3, ...
So a link that uses the old slug of a third or later duplicate, such as[](#x-1-2), no longer resolves
and warns (myst.xref_missing, which fails a-Wbuild): change it to[](#x-2).
Links to the first two duplicates are unchanged, and every HTML id a heading had before is kept. - Slugs are also emitted as secondary HTML
ids on the rendered headings, so#sluglinks work in the published HTML.
The docutils id stays the primary (first) id, so existing fragment links keep working.
Setmyst_heading_anchors_html_ids = Falseto emit only the docutils id. - An explicit
(target)=placed before a heading becomes the section's primary id,
which tocs, permalinks andobjects.invuse; the implicit heading id is kept as a secondary anchor. - A heading whose slug is empty (a punctuation-only title, or any non-Latin title with the
"docutils"preset) gets no anchor,
and an empty fragment,[](#), now warns as unresolved. - Links that used to warn now resolve when the anchor exists:
same-document links to implicit ids (such as headings deeper thanmyst_heading_anchors; under Sphinx only as a last resort),
and cross-document links to label ids and to the implicit ids of headings within themyst_heading_anchorsdepth.
[](doc.md#label)takes the target's title as its text (#1207). - These rules (slug presets, deduplication, empty slugs, explicit-id priority and HTML ids) are now a documented contract,
pinned by a versioned, language-agnostic corpus (tests/fixtures/slugs.json).
myst_parser.mdit_to_docutils.base.default_slugifyis deprecated in favour ofmyst_parser.slugs.github_slugify.
- Duplicate heading slugs now get fixed-base suffixes,
- Directive option warnings (#1164): each warning now points at the offending option's line,
and unknown options are reported one per warning, asUnknown option key: 'x' (allowed: [...]),
instead of one aggregateUnknown option keys: [...].
Themyst.directive_optionsubtype is unchanged, sosuppress_warningskeeps working,
but tests that match the old message need updating. - Directive API (#1164): directives now receive the full fenced text as
block_text, as in reStructuredText,
so errors that echo it show the whole fence;
andcontent_offsetis-1when the body starts on the opening line. - Source lines (#1164, #1169, #1179): lines in warnings and nodes change where they were wrong.
Text nodes no longer take the line of the most recent directive (so gettext.potlocations change),
lines inside{include}d files are no longer one late,
and the body of a directive with options and a trailing blank line is no longer one line off. - Front matter (#1197): options that can only be set globally
(heading_slug_func,update_mathjax,mathjax_classes,suppress_warnings,inventories)
now warn (myst.topmatter) and are ignored in a document's front matter.
This removes the undocumented per-document effect ofinventories(docutils) andupdate_mathjax(Sphinx). - Rendered output:
parsed-literalkeeps each line's indentation, and two trailing spaces no longer make a hard line break (#1176);$$math blocks lose the blank lines at the start and end of their content, which broke LaTeX output (#1224);myst_links_external_new_tabwritesrel="noreferrer"(it was misspeltnoreferer),
and no longer overwrites an authoredtargetorrel(#1200);- image alt text keeps backslash escapes and entities (#1211),
an HTML<img>keeps its alt text exactly, and a valuelessaltis now empty rather thanNone(#1214); - link titles are kept on links that go through cross-reference resolution (#1196);
- a footnote whose label equals a heading's name is now kept, rather than dropped with a warning (#1157).
- Packaging (#1221): the distributions are now built with
python -m build,
so the sdists hold only the package,pyproject.toml,README.mdandLICENSE
(no longerCHANGELOG.md,tox.inior.github/); the wheels are unaffected. - mdit-py-plugins 0.7 (#1170): myst-parser and myst-docutils now require
mdit-py-plugins>=0.7,<1.
✨ New Features
- ✨ Stable heading anchors: one shared slug module (
myst_parser.slugs), named presets formyst_heading_slug_func("github","gitlab"), slugs emitted as HTML ids (myst_heading_anchors_html_ids), explicit-id priority, fewer false warnings for working links, andmyst-anchors --slug-func, by @chrisjsewell in #1158 - ✨ Add the
"docutils"heading slug preset (byte-identical todocutils.nodes.make_id) and a versioned anchor contract, see docs, by @chrisjsewell in #1168 - ✨ Add the
"section_ref"syntax extension: section-sign references such as§1,§1.1and§2.3.4link to the correspondingly numbered heading of the current document (numbered the same in docutils and Sphinx), with a suppressiblemyst.section_refwarning when no heading matches, see docs, by @chrisjsewell in #1170
👌 Improvements
- 👌 Report accurate source lines: directive option warnings point at their option, unknown options warn per key, first-line directive content is no longer one line off, text nodes get their own lines (#546), directives receive the full
block_text(superseding #1048, thanks to @kdeldycke), and anincludewith:literal:gets its true line, by @chrisjsewell in #1164 - 👌 Allow a
{table}caption to wrap onto the following lines, by @BetterAndBetterII in #1195 - 👌 Make a document's own front matter available to its substitutions, as
env.metadata[env.docname], by @holmboe in #1171
🐛 Bug Fixes
- 🐛 Warn instead of aborting the build on hostile input (deeply nested HTML, malformed or hostile YAML front matter, YAML alias bombs), and keep a footnote whose label equals a heading's name, by @chrisjsewell in #1157
- 🐛 Fix small docutils renderer bugs: field bodies get source lines, a definition without a term no longer crashes, and
linkifywithoutlinkify-it-pyinstalled is disabled with amyst.linkifywarning instead of crashing, by @chrisjsewell in #1153 - 🐛 Resolve
[](doc.md#label)links to explicit targets in other documents without a falsemyst.xref_missingwarning (#1151, reported by @kdeldycke), using the target's title as the link text, by @dstrodtman in #1207 - 🐛 Keep link titles through cross-reference resolution, by @dylanpulver in #1196
- 🐛 Report exact source lines in
{include}d files (also with:start-after:and a negative:start-line:), by @chrisjsewell, @dchaudhari7177, @vishalkaay and @Sanjays2402 in #1169 - 🐛 Keep validated front matter config values (
enable_extensions,fence_as_directive,url_schemes), and reject `global_onl...
v5.1.0
✨ New Features
- ✨ Add
"alert"syntax extension for GFM alerts (e.g.> [!NOTE]), see docs by @chrisjsewell in #1128 - ✨ Add
"gfm_autolink"syntax extension for GFM autolinks, see docs by @chrisjsewell in #1128 - ✨ Add
myst_strikethrough_single_tildeconfig option to allow single tilde (~) for strikethrough by @chrisjsewell in #1128 - ✨ Add
myst_colon_fence_exact_matchconfig option to require the closing colon fence to have exactly the same number of colons as the opening, see docs by @chrisjsewell in #1128
👌 Improvements
- 👌 Update
myst_gfm_onlymode to use the unifiedgfm_plugin, which now includes GFM autolinks, alerts, and improved strikethrough/tasklist handling by @chrisjsewell in #1128 - 👌 Improve MathJax 4 compatibility for Sphinx 9 by @chrisjsewell in #1110
- 👌 Stop directive-option parsing at colon fences, fixing nested colon fence directives by @chrisjsewell in #1133
🐛 Bug Fixes
- 🐛 Use docname instead of source path in warning locations by @chrisjsewell in #1114
- 🐛 Correctly encode
&in Markdown URLs by not HTML-escapingrefuriby @chrisjsewell in #1126 - 🐛 Fix
RemovedInSphinx10Warningfor inventory item iteration by @chrisjsewell in #1129 - 🐛 Pin
mdit-py-plugins>=0.6.1for nested field list fix by @chrisjsewell in #1134
⬆️ Dependency Upgrades
- ⬆️ Upgrade to
markdown-it-py~=4.2andmdit-py-plugins~=0.6by @chrisjsewell in #1128 - ⬆️ Update pygments requirement from
<2.20to<2.21by @chrisjsewell in #1117
New Contributors
- @mb made their first contribution in #1126
- @Bizordec made their first contribution in #1114
- @ilia-kats made their first contribution in #1110
Full Changelog: v5.0.0...v5.1.0
v5.0.0
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.mdby @krassowski in #1036
🔧 Internal / Maintenance
- 🔧 Update pre-commit by @chrisjsewell in #1058
- 🔧 Add
AGENTS.mdby @chrisjsewell in #1083
Full Changelog: v4.0.1...v5.0.0
v4.0.1
What's Changed
-
🔧 Minor fix for sphinx 8.2 compat by @chrisjsewell in #1013
-
🔧 Fix type of MockIncludeDirective’s
klassparameter by @flying-sheep in #975 -
📚 remove redundant paragraph by @Snoopy1866 in #987
New Contributors
- @cclauss made their first contribution in #969
- @flying-sheep made their first contribution in #975
- @Snoopy1866 made their first contribution in #987
- @goekce made their first contribution in #990
Full Changelog: v4.0.0...v4.0.1
v4.0.0
What's Changed
- ⬆️ Support python>=3.10, sphinx >=7,<9, docutils>=0.19,<0.22 by @chrisjsewell in #952
- 👌 Improve footnote def/ref warnings and translations by @chrisjsewell in #931
- 📚 Fix typo by @meli-lewis in #940
New Contributors
- @meli-lewis made their first contribution in #940
Full Changelog: v3.0.1...v4.0.0
v3.0.1
What's Changed
- 🐛 FIX empty value for final directive option by @chrisjsewell in #924
- 🐛 FIX: allow indented option block by @chrisjsewell in #925
Full Changelog: v3.0.0...v3.0.1
v3.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-blockdirective by @chrisjsewell in #900 - ✨ Emits sphinx include-read event by @sumezulike in #887
Improvements
- 👌 Nested parse attribution in
attr_blockby @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
usedin 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
v2.0.0
This release primarily updates core myst-parser dependencies,
with some minor changes to parsing behaviour:
-
⬆️ UPGRADE:
markdown-it-pyto 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-pyto 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
docutilsv0.20 (https://github.com/executablebooks/MyST-Parser/775) -
⬆️ UPGRADE: Add support for
sphinxv7, and remove v5 support (https://github.com/executablebooks/MyST-Parser/776) -
⬆️ 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 nota-b-c
- This change makes the slug generation closer to GitHub, in that, starting/ending whitespace will not be stripped.
-
👌 IMPROVE: Substitution extension (https://github.com/executablebooks/MyST-Parser/777)
- Allow any value type (including dict, list, datetime) and emit a
myst.substitutionwarning for errors in resolving the substitution content.
- Allow any value type (including dict, list, datetime) and emit a
-
🧪 Introduce a gate/check GHA job, thanks to @webknjaz (https://github.com/executablebooks/MyST-Parser/635)
Full Changelog: v1.0.0...v2.0.0
v1.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 😄
v0.19.2
What's Changed
- ✨ NEW: Add
myst_fence_as_directiveconfig 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
Full Changelog: v0.19.1...v0.19.2