Skip to content

Releases

v5.2.0

Choose a tag to compare

@chrisjsewell chrisjsewell released this 10 Nov 19:53
5137add

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 get x-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 -W build): 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 #slug links work in the published HTML.
      The docutils id stays the primary (first) id, so existing fragment links keep working.
      Set myst_heading_anchors_html_ids = False to emit only the docutils id.
    • An explicit (target)= placed before a heading becomes the section's primary id,
      which tocs, permalinks and objects.inv use; 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 than myst_heading_anchors; under Sphinx only as a last resort),
      and cross-document links to label ids and to the implicit ids of headings within the myst_heading_anchors depth.
      [](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_slugify is deprecated in favour of myst_parser.slugs.github_slugify.
  • Directive option warnings (#1164): each warning now points at the offending option's line,
    and unknown options are reported one per warning, as Unknown option key: 'x' (allowed: [...]),
    instead of one aggregate Unknown option keys: [...].
    The myst.directive_option subtype is unchanged, so suppress_warnings keeps 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;
    and content_offset is -1 when 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 .pot locations 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 of inventories (docutils) and update_mathjax (Sphinx).
  • Rendered output:
    • parsed-literal keeps 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_tab writes rel="noreferrer" (it was misspelt noreferer),
      and no longer overwrites an authored target or rel (#1200);
    • image alt text keeps backslash escapes and entities (#1211),
      an HTML <img> keeps its alt text exactly, and a valueless alt is now empty rather than None (#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.md and LICENSE
    (no longer CHANGELOG.md, tox.ini or .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 for myst_heading_slug_func ("github", "gitlab"), slugs emitted as HTML ids (myst_heading_anchors_html_ids), explicit-id priority, fewer false warnings for working links, and myst-anchors --slug-func, by @chrisjsewell in #1158
  • ✨ Add the "docutils" heading slug preset (byte-identical to docutils.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.1 and §2.3.4 link to the correspondingly numbered heading of the current document (numbered the same in docutils and Sphinx), with a suppressible myst.section_ref warning 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 an include with :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 linkify without linkify-it-py installed is disabled with a myst.linkify warning instead of crashing, by @chrisjsewell in #1153
  • 🐛 Resolve [](doc.md#label) links to explicit targets in other documents without a false myst.xref_missing warning (#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...
Read more

v5.1.0

Choose a tag to compare

@chrisjsewell chrisjsewell released this 13 May 09:35
2871eb9

✨ New Features

👌 Improvements

  • 👌 Update myst_gfm_only mode to use the unified gfm_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

⬆️ Dependency Upgrades

New Contributors

Full Changelog: v5.0.0...v5.1.0

v5.0.0

Choose a tag to compare

@chrisjsewell chrisjsewell released this 15 Jan 09:06
a139a1f

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

👌 Improvements

📚 Documentation

🔧 Internal / Maintenance

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

v4.0.1

Choose a tag to compare

@chrisjsewell chrisjsewell released this 12 Feb 10:50
8a44f5d

What's Changed

  • 🔧 Minor fix for sphinx 8.2 compat by @chrisjsewell in #1013

  • 🧪 Add CI testing support for Python 3.13 by @hugovk in #955

  • 🔧 Fix type of MockIncludeDirective’s klass parameter by @flying-sheep in #975

  • 📚 Fix typos discovered by codespell by @cclauss in #969

  • 📚 remove redundant paragraph by @Snoopy1866 in #987

  • 📚 Minor typo in cross-referencing.md by @goekce in #990

New Contributors

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

v4.0.0

Choose a tag to compare

@chrisjsewell chrisjsewell released this 05 Aug 14:00
ce37be5

What's Changed

New Contributors

Full Changelog: v3.0.1...v4.0.0

v3.0.1

Choose a tag to compare

@chrisjsewell chrisjsewell released this 28 Apr 20:20
3d84ff8

What's Changed

Full Changelog: v3.0.0...v3.0.1

v3.0.0

Choose a tag to compare

@chrisjsewell chrisjsewell released this 23 Apr 14:34
1b44e06

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

Improvements

Internal

Documentation

New Contributors

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

v2.0.0

Choose a tag to compare

@chrisjsewell chrisjsewell released this 13 Jun 16:26
4ae5863

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

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

v1.0.0

Choose a tag to compare

@chrisjsewell chrisjsewell released this 07 Mar 18:37
0271d68

🎉 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

Choose a tag to compare

@chrisjsewell chrisjsewell released this 07 Mar 18:24
f4afeef

What's Changed

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