Number align/gather rows per-row (amsmath semantics) — honor per-row \label, \tag, \nonumber

[mmcky]

Summary

Under book-mode numbering, mystmd assigns one equation number per display-math block, regardless of its contents. A LaTeX align (and gather / flalign / alignat) numbers each \\ row — minus any row carrying \nonumber / \notag. So a multi-row align that the source numbers as N equations renders as a single number in mystmd, and every labelled equation after it drifts off the source's numbering. This breaks cross-document citation parity ("see equation (1.15) in the printed script" points at a different equation in the HTML).

What LaTeX (amsmath) does

Equation numbering is per-environment-class, not uniform. The row-numbering envs are the gap:

Environment	LaTeX numbering
equation, multline	exactly one number per environment
align, gather, flalign, alignat, eqnarray	one number per \\ row, suppressed on rows with \nonumber / \notag
equation* / align* / \[ \] / $$	unnumbered
per-row \label{…}	anchors that row's number for \ref / \eqref
\tag{…} / \tag*{…}	overrides a row's auto-number with a manual tag

Current mystmd behavior (probe)

Built with numbering: { book: { enabled: true }, chapters: { label: "Chapter %s" } } and a page enumerator 1.%s:

$$
\begin{align}
a &= b \\
c &= d
\end{align}
$$

$$
\begin{align}
x &= y \label{eq-xy} \\
u &= v \nonumber \\
w &= z
\end{align}
$$

Resulting AST math nodes:

enumerator=1.1  label=None    value="\begin{align} a &= b \\ c &= d \end{align}"
enumerator=1.2  label=eq-xy   value="\begin{align} x &= y \label{eq-xy} \\ u &= v \nonumber \\ w &= z \end{align}"

So mystmd:

• numbers the whole align block once (1.1), not once per row;
• ignores the \\ row boundaries for numbering;
• collapses a per-row \label to the block's label rather than the row's;
• ignores \nonumber / \notag entirely (the block still takes one number).

Raw \begin{align} and \begin{aligned} behave identically here — both are one enumerated node.

Requested behavior

For a display-math block whose body is a row-numbering environment (align, gather, flalign, alignat, and the eqnarray legacy), number each \\ row with the active enumerator:

• a row with no \nonumber / \notag advances the counter and shows its own number;
• a row with \nonumber / \notag renders but takes no number (counter does not advance);
• a per-row \label{…} becomes that row's anchor, so \ref / \eqref resolves to the row's number;
• a per-row \tag{…} / \tag*{…} overrides that row's number;
• equation / multline stay one-number (already correct); align* and friends stay unnumbered.

This mirrors amsmath's per-row numbering exactly, so a document authored in LaTeX and published through mystmd shows the same equation numbers.

Why this belongs in mystmd, not the converter

The LaTeX → MyST converter (QuantEcon/claude-latex-to-myst, issue jupyter-book#186 is the downstream consumer) already emits valid, well-formed MyST for these blocks — the numbering information is present in the source and reaches the AST intact (see the probe: the \\, \label, and \nonumber all survive into value). The only converter-side way to recover per-row numbers is to split each row into a separate $$…$$, which throws away the & column alignment that is the whole point of align. That is a rendering regression, not a fix. Numbering rows while keeping them aligned is something only the renderer can do — hence a mystmd feature rather than a converter workaround.

Payoff: once mystmd numbers align natively, the converter can pass these environments through verbatim (as it already does for equation) instead of rewriting them to aligned, so both sides get simpler and equation numbering matches the source PDF for free.

Related

• Per-heading unnumbered control under book-mode numbering #68 (per-heading unnumbered control under book-mode numbering) — same family: source numbering intent the renderer currently can't express.
• prf:algorithm: support continuous line numbering for algorithm2e-style algorithms (nested blocks restart at 1) #70 (prf:algorithm continuous line numbering) — the per-row-numbering analog for algorithm lines.
• Downstream consumer / motivation: QuantEcon/claude-latex-to-myst#186 (equation-number drift vs. the printed PDF in the deep-learning book).