[chrisjsewell]

Release myst-parser and myst-docutils 5.2.0.

• myst_parser/__init__.py: __version__ = "5.2.0" (the only version location; pyproject.toml reads it dynamically).
• CHANGELOG.md: the 5.2.0 entry, covering every PR merged since v5.1.0, with an Upgrade notes section for the changes that can alter the output of a project that built before (heading anchors: links that use the old slug of a third or later duplicate heading, such as , must be rewritten; directive option warning text; block_text/content_offset; source lines; global_only front matter keys; rendered-output fixes; sdist contents).
  Left out as CI, tooling or test only: ⬆️ Bump actions/setup-python from 6 to 7 #1226, ⬆️ Bump actions/checkout from 6 to 7 #1148, [pre-commit.ci] pre-commit autoupdate #1162, ⬆️ Bump ruff from 0.15.13 to 0.15.20 #1150, ⬆️ Bump ruff from 0.15.12 to 0.15.13 #1138, [pre-commit.ci] pre-commit autoupdate #1137, 🧪 Add regression test for code fences inside GFM alert blocks #1142, 🔧 Disable "colorrows" latex table style to fix PDF docs build #1154.

The entry is dated 2026-11-10: re-date it to the tag day before merging if they differ.

No code, test or CI changes.

Decide before the tag

• ✨ NEW: Add section_ref syntax extension (§1.1 heading references) #1170 (section_ref): IN this release (merged as 7d48de0 once ubCode's implementation landed); its changelog entry, upgrade note and the mdit-py-plugins~=0.7 runtime floor are in the entry.
• myst-docutils runtime docutils range: unchanged from 5.1.0 (declared only under its sphinx extra); deferred to 5.3.0.

Checks run on this branch

• pytest (py3.13, Sphinx 9.2.0, docutils 0.23): 1514 passed, 11 skipped, with markdown-it-py 4.2.0 + mdit-py-plugins 0.6.1 from PyPI, and the same with markdown-it-py and mdit-py-plugins installed from their maint/release-v4.3.0 / maint/release-v0.7.0 branches (markdown-it-py b5095c1, 4.3.0; mdit-py-plugins 13974a7, 0.7.0: their release commits), 1514 passed, 11 skipped.
• pre-commit run --all-files: all hooks pass.
• sphinx-build -nW --keep-going -b html docs/ docs/_build/html -P: no warnings.
• The CI build job's steps: both distributions build, twine check --strict passes on all four files, and the tag check accepts v5.2.0 and rejects v5.2.1.

Before the tag

• markdown-it-py 4.3.0 and mdit-py-plugins 0.7.0 are on PyPI, and the MyST suite passes against them (or the result is recorded as "re-check after their release").
• RTD builds this PR and the merge commit green.
• sphinx-needs accepts the new unknown-option warning text: done in 🧪 sphinx-test-reports: accept myst-parser 5.2's unknown-option warning text useblocks/sphinx-needs#2501 (test_extra_option_case.py; the docs no longer quote the old message).
• The myst-nb test suite passes against this branch.
• Downstream rehearsal against this branch: sphinx-design main (after its MyST-compat test fix), sphinx-subfigure, sphinx-jinja2 and the sphinx-needs suite.

Release checklist

• Publishing setup: PyPI trusted publishers are registered for both myst-parser and myst-docutils (workflow tests.yml, environment pypi). gh api repos/executablebooks/MyST-Parser/environments shows pypi with a custom deployment policy v* (type tag) and no required reviewer (and an unrelated copilot environment).
• Squash-merge this PR, then tag the squash commit: git tag v5.2.0 <sha> && git push origin v5.2.0.
• The continuous-integration run for the tag is green, including Publish myst-parser to PyPI and then Publish myst-docutils to PyPI. If a publish job fails, fix the configuration and re-run the job; never re-tag.
• Provenance returns 200 for all four files: https://pypi.org/integrity/myst-parser/5.2.0/myst_parser-5.2.0-py3-none-any.whl/provenance, …/myst_parser-5.2.0.tar.gz/provenance, https://pypi.org/integrity/myst-docutils/5.2.0/myst_docutils-5.2.0-py3-none-any.whl/provenance, …/myst_docutils-5.2.0.tar.gz/provenance (5.1.0 returns 404: it was a token upload).
• Draft the GitHub Release v5.2.0 from the changelog entry.
• RTD builds the tag, and stable (active, today on v5.1.0) moves to v5.2.0.
• conda-forge (conda-forge/myst-parser-feedstock, recipe/meta.yaml, today at 5.1.0): run deps docutils >=0.20,<0.23 → >=0.20,<0.24; markdown-it-py >=4.2.0,<4.3.0 → >=4.2,<5 (the feedstock's cap is tighter than our ~=4.2 and would block markdown-it-py 4.3.0); mdit-py-plugins >=0.6.1,<0.7 → >=0.7,<1 (5.2.0 requires 0.7 for section_ref); host flit-core >=3.4,<4 → >=3.4,<5; Python floor unchanged (3.11). Its myst-benchmark entry point names a module that no longer exists. There is no myst-docutils feedstock.
• After the first green trusted-publishing release: revoke the old PyPI tokens and delete the PYPI_KEY / PYPI_KEY_DOCUTILS secrets.
• Follow-ups: close the issues and PRs fixed in this release with a "Released in 5.2.0" note; merge use pathlib #1159 (pathlib) right after the tag; make myst-docutils require docutils at runtime (.github/workflows/docutils_setup.py); start the 5.3.0 queue (🐛 Accurate directive line mapping and source-attributed nested renders #1175, ✨ Expose MyST substitutions to reStructuredText #1194, NEW: Reference amsmath environments by their \label #1215, Support building line blocks with markdown-it hardbreaks #948).

Squash commit

Title: 🚀 RELEASE: v5.2.0 (#1228)

Bump the version to 5.2.0 and add the 5.2.0 changelog entry, with
upgrade notes for the changes that can alter the output of a project
that built before.