fix: align MyST heading slugs with docutils section IDs (#550)

MyST's default slug function uses GitHub-style heading IDs that preserve
leading digits ("3.3 Toolchain Management" -> "33-toolchain-management"),
but Sphinx section IDs are generated by docutils' make_id which strips
them ("toolchain-management"). This mismatch causes spurious
myst.xref_missing warnings on valid [text](file.md#anchor) cross-
references whenever a heading starts with a numeric prefix.

Set myst_heading_slug_func to docutils.nodes.make_id so both sides
agree. Also enable myst_heading_anchors=4 so MyST can resolve heading
cross-references up to h4 depth.

Both settings use config_setdefault, so projects can still override them
in their own conf.py.

Author: AlexanderLanin

src/extensions/score_sphinx_bundle/__init__.py

@@ -64,6 +64,18 @@ def setup(app: Sphinx) -> dict[str, object]:
     for e in score_extensions:
         app.setup_extension(e)
 
+    # Enable cross-reference resolution for [text](file.md#anchor) links up to h4.
+    # Without this, MyST treats heading anchors as opaque and cannot resolve them.
+    config_setdefault(app.config, "myst_heading_anchors", 4)
+
+    # MyST's default slug function uses GitHub-style heading IDs that keep leading
+    # digits ("3.3 Toolchain Management" -> "33-toolchain-management"), but docutils'
+    # make_id strips them ("toolchain-management"). Since Sphinx section IDs are
+    # generated by docutils, the two algorithms disagree whenever a heading starts
+    # with a numeric prefix, causing myst.xref_missing warnings on valid cross-
+    # references. Aligning MyST's slug function on make_id fixes the mismatch.
+    config_setdefault(app.config, "myst_heading_slug_func", "docutils.nodes.make_id")
+
     # enable "..."-syntax in markdown — must come after myst_parser is loaded above
     if isinstance(app.config.myst_enable_extensions, list):
         app.config.myst_enable_extensions.append("colon_fence")