Upstream context for citation @-parsing: code-span guard (PR #53) vs the escaping discussion

[mmcky]

Documents a survey of upstream jupyter-book/mystmd issues and discussions around overzealous citation @-parsing, and how our code-span guard (#46, implemented in PR #53) relates to it. No action required — this is reference material for the eventual upstream PR.

Upstream landscape (as of 2026-06-12)

Thread	State	Shape	Outcome / stance
jupyter-book#1618	open, bug	[@handle](url) link labels	One maintainer comment (agoose77, Nov 2024) leaning toward explicit escaping (\@rowanc1): "treating @ as special is probably the easiest to reason about"
jupyter-book#2538	closed	bare URLs (hackmd.io/@user/…)	Fixed by upstream PR jupyter-book#2684 "Make citation parsing less aggressive" — the isUrlContext/isLinkContext guards now in citations.ts
jupyter-book#2891	merged PR	@mention followed by inline HTML	Another incremental "narrow the parsing context" fix to the same rule
jupyter-book#1629	open	DOI-in-link → cite over-conversion	Same "less aggressive cite" theme, but in the link transform (myst-cli dois.ts), not the parser
jupyter-book#2942	open	mdast spec for citations	Data-structure design discussion; also questions whether pandoc [@key] syntax is the settled direction

The inline-code-span shape is unreported upstream — no issue covers an @-token enclosed in backticks inside a bracket. Our #46 / PR #53 is therefore complementary to all in-flight upstream work, not in conflict with any of it.

Why the escaping philosophy does not cover our case

The only stated upstream stance (jupyter-book#1618 comment) is user-side escaping. That cannot work for the code-span shape:

• In CommonMark, backslashes inside code spans are literal — `\@tf.function` renders the backslash. There is no way to escape an @ inside backticks.
• The only available workaround is escaping the bracket (**\[NEW: …), which is non-obvious and changes link semantics — this is what the Deep_Learning book's conversion currently does, and what PR Citation scanner respects inline code-span boundaries #53 makes unnecessary.
• Code spans binding tighter than brackets is CommonMark's own inline precedence; the guard restores spec-consistent behavior rather than adding a heuristic.

So even if upstream resolves jupyter-book#1618 via escaping, the code-span guard remains necessary and orthogonal. Conversely, upstream's merge history on citations.ts (jupyter-book#2684, jupyter-book#2891) shows repeated acceptance of exactly this kind of context-narrowing fix, so the cherry-pick has good precedent.

How this feeds the upstream PR

When PR #53's squash commit is added to quantecon/UPSTREAM-PRS.yml, the candidate notes should carry:

1. the escape-impossibility argument above (the core of the upstream pitch),
2. the relationship to Links that start with @ are treated as citations even if they're not jupyter-book/mystmd#1618 (related link shape, explicitly not addressed here), and
3. the precedent chain (URLs with @ symbols in them are parsed as citations jupyter-book/mystmd#2538 → Make citation parsing less aggressive jupyter-book/mystmd#2684, 🐛 Citation @mention followed by html parsing bug jupyter-book/mystmd#2891).

We decided not to file an upstream issue pre-emptively; the context lands with the upstream PR itself.