[dependabot]

Bumps myst-parser from 5.1.0 to 5.2.0.

Release notes

Sourced from myst-parser's 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 get x-1-2, x-1-2-3, ... So a link that uses the old slug of a third or later duplicate, such as [](https://github.com/executablebooks/MyST-Parser/blob/HEAD/#x-1-2), no longer resolves and warns (myst.xref_missing, which fails a -W build): change it to [](https://github.com/executablebooks/MyST-Parser/blob/HEAD/#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, [](https://github.com/executablebooks/MyST-Parser/blob/HEAD/#), 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. [](https://github.com/executablebooks/MyST-Parser/blob/HEAD/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)

... (truncated)

Changelog

Sourced from myst-parser's changelog.

5.2.0 - 2026-11-10

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 (gh-pr:1158, gh-pr:1168), see :
  • 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 [](https://github.com/executablebooks/MyST-Parser/blob/master/#x-1-2), no longer resolves and warns (myst.xref_missing, which fails a -W build): change it to [](https://github.com/executablebooks/MyST-Parser/blob/master/#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, [](https://github.com/executablebooks/MyST-Parser/blob/master/#), 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. [](https://github.com/executablebooks/MyST-Parser/blob/master/doc.md#label) takes the target's title as its text (gh-pr: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 (gh-pr: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 (gh-pr: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 (gh-pr:1164, gh-pr:1169, gh-pr: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 (gh-pr:1197): options that can only be set globally

... (truncated)

Commits

• 5137add 🚀 RELEASE: v5.2.0 (#1228)
• 7d48de0 ✨ NEW: Add section_ref syntax extension (§1.1 heading references) (#1170)
• a99fd5e 📚 DOCS: suppress sphinx-design 0.8.0's design.card_legacy warning (#1229)
• dde8f25 ⬆️ Allow flit_core 4 as build backend (#1185)
• 1915654 🐛 FIX: exact source lines in {include}d files (#1169)
• 253427e 🐛 FIX: keep validated topmatter config, and enforce global_only (#1197)
• 03ffdcd ⬆️ Bump actions/setup-python from 6 to 7 (#1226)
• d9c9991 🐛 FIX: Allow a {table} caption to wrap onto the following lines (#1195)
• 81b0be5 🐛 FIX: Make a document's own front matter available in env.metadata (#1171)
• fc00785 🐛 FIX: Keep link titles through cross-reference resolution (#1196)
• Additional commits viewable in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

---

Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR:

• @dependabot rebase will rebase this PR
• @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
• @dependabot show <dependency name> ignore conditions will show all of the ignore conditions of the specified dependency
• @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)