Per-heading unnumbered control under book-mode numbering

[mmcky]

Summary

Under numbering.book.enabled (and more generally when a heading depth is enabled), every heading at that depth is numbered, and there is no way to exclude an individual heading. LaTeX \section*{...} and \paragraph{...} are unnumbered by design, so converting them faithfully to MyST needs a per-heading opt-out. Today mystmd offers only all-or-nothing control per heading depth.

What I tried (mystmd v1.10.1, QuantEcon qe-v8 fork)

Neither of the attribute forms one might expect is parsed as an attribute on an ATX heading — the whole {…} block leaks into the rendered heading text:

Source	Rendered heading text	Heading id
## Summary {.unnumbered}	Summary {.unnumbered}	auto-slug of the leaked text (summary-unnumbered)
## Summary {#summary .unnumbered}	Summary {#summary .unnumbered}	comes only from a preceding (label)= target, never from the {#…} block

So ids are set via the (label)= target syntax, and there is no class/attribute channel on headings through which an "unnumbered" hint could be passed.

Request

A per-heading way to exclude a single heading from automatic numbering — for example honoring enumerated: false (or a .unnumbered class) on a heading node. This would let downstream tooling represent unnumbered sections faithfully while keeping them in the document/TOC.

Why it matters

This surfaced converting QuantEcon/book-dp2 from LaTeX. Each chapter's \section*{Summary} and the run-in \paragraph headings are unnumbered in the source/PDF, but in the MyST build they pick up section numbers (e.g. "Summary" numbered §1.5, pushing "Chapter Notes" to §1.6; a \paragraph carrying a full multi-level number like §8.3.1.2.1). With no per-heading opt-out, the only faithful alternatives both lose information: keep the heading and accept a wrong number, or demote it to bold run-in text and lose the TOC entry and anchor.

Happy to provide a minimal reproducing project if useful.

[mmcky]

Re-verified on main (44cf0621, v1.10.1 qe-v8) — and the ask is smaller than the original write-up makes it look. Both halves of this already exist in the codebase; what's missing is a connector between them.

The numbering machinery already supports it

shouldEnumerateNode gives a node the first and final word on its own enumeration, before any frontmatter lookup:

// packages/myst-transforms/src/enumerate.ts:406-407
// Node may override enumeration from numbering frontmatter
if (node.enumerated != null) return node.enumerated;

And addTarget gates the counter on that same result, so an enumerated: false node is skipped and does not advance the count:

// packages/myst-transforms/src/enumerate.ts:661-664
const numberNode = !hidden && shouldEnumerateNode(node, kind, this.numbering, this.offset);
if (numberNode) {
  this.incrementCount(node, kind as TargetKind);
}

That is exactly LaTeX \section* semantics — the starred section is unnumbered and invisible to the counter, so the next real section keeps the number it would have had. It is also already a live, exercised path for {math} (:enumerated: false) and the proof family. The target itself is still registered and html_id is still assigned (lines 665-667), so an unnumbered heading keeps its anchor and its TOC entry — the two things the original write-up said we'd have to trade away.

The attribute parser already exists too

packages/markdown-it-myst/src/inlineAttributes.ts already tokenizes .className, #id, key="value" and bare tokens (tokenizeInlineAttributes, line 19; inlineOptionsToTokens, line 72). It is currently wired only to directives (directives.ts:8) and roles (roles.ts:5).

So the request reduces to

Wire inlineAttributes to ATX heading tokens and map the result onto the heading node: .unnumbered → enumerated: false, #id → identifier, and (optionally) .unlisted → excluded from the TOC. This is pandoc's own heading-attribute syntax, which means LaTeX-derived content arrives already carrying the right marker.

What I probed (same build, book-mode numbering, numbering.book.enabled: true)

Neither existing route reaches the heading node:

Source	Heading text in AST	enumerator	Note
## Summary {.unnumbered}	Summary {.unnumbered}	1.2	attribute block leaks into the title; id becomes summary-unnumbered
+++ {"enumerated": false} then ## Block Meta Summary	Block Meta Summary	1.4	the flag does land as block.data.enumerated === false, but never propagates to the heading
(sec-a)= then ## Section A	Section A	1.1	baseline

Scale, updated

The original report cited two \section*{Summary} headings in book-dp2. Since then we converted Deep Learning for Solving and Estimating Dynamic Models, which puts a \section*{Further Reading} and a \section*{Exercises} at the end of nearly every chapter. In the built AST that is 23 headings carrying numbers they should not have:

File	Heading	Enumerator
ch01_intro	Further Reading / Exercises	1.12 / 1.13
ch02_deqns	Further Reading / Exercises	2.10 / 2.11
ch03_irbc	Further Reading / Exercises	3.7 / 3.8
ch04_nas	Further Reading / Exercises	4.9 / 4.10
ch05_olg	Further Reading / Exercises	5.6 / 5.7
ch06_ha_youngs	Further Reading / Exercises	6.8 / 6.9
ch07_pinns	Further Reading / Exercises	7.10 / 7.11
ch08_ctime_ha	Further Reading / Exercises	8.9 / 8.10
ch09_surrogates_gps	Further Reading / Exercises	9.9 / 9.10
ch10_smm	Further Reading / Exercises	10.1.6 / 10.1.7
ch11_climate	Further Reading / Exercises	11.14 / 11.15
ch12_synthesis	Exercises	12.9

The same book also has a chapter whose sections are hand-numbered in the title (\section*{1. Motivation} … \section*{8. Takeaways}), which currently render as "8.1 1. Motivation".

Happy to open a PR against the fork if the approach above looks right.