Process mermaid %%| cell options: captions, cross-references, alt text (bd-mermaid-cell-options-9wo3crl0)

[cscheid]

Processes mermaid %%| cell options, so fig-cap / fig-alt on a
```mermaid fence reach the output instead of sitting verbatim in the
diagram source (bd-mermaid-cell-options-9wo3crl0).

Plan, design rationale and full verification record:
claude-notes/plans/2026-08-10-mermaid-cell-options.md.

The finding that shaped this

The caption / figure / crossref machinery already worked for a mermaid
fence — it just keyed off the #| marker. At the previous HEAD, a
```mermaid block with #| label: + #| fig-cap: rendered a full
quarto-float figure with numbering and aria-describedby; only the %%|
spelling was unrecognized. cell_options::comment_syntax_for had no mermaid
entry, because Q1 keeps mermaid's %% on the language handler and in
constants.lua rather than in kLangCommentChars, which is what that table
was ported from.

The architectural constraint: this has to happen in PreEngineSugaringStage,
not in transforms/mermaid.rs. That transform is on
Q2_PREVIEW_TRANSFORM_EXCLUDED (so preview would diverge) and runs after
crossref-render (so a label: could never be numbered). Doing it pre-engine
gives preview/render parity for free.

What changed, commit by commit

cell_options learns mermaid's %%	with a cross-talk test against matlab/tikz's single %
shorthand migrated onto cell_options	language-aware marker + real YAML parsing, replacing a private `#
fig-cap parsed as markdown inlines	via the same entry point document metadata uses
unlabelled fig-cap → Block::Figure	fig-scap → Caption::short
fig-alt → mermaid's accDescr:	and stop consuming options we cannot route
Q-2-47 / Q-2-48 diagnostics	source-mapped to the offending key
preview-parity test, docs, worked example

Three pre-existing defects in the shared #| shorthand are fixed along the
way — all reproduced on a plain ```python cell first, so they were
never mermaid-specific:

• bd-5jcmmj1f — fig-cap: "A caption." rendered as Figure 1: "A caption."
  with literal quote characters.
• bd-sdpp9rw4 — fig-cap: A *strong* claim rendered the asterisks
  literally.
• bd-il6pxq4f — fig-alt and fig-scap were consumed (stripped from the
  body) but never read back out; the text vanished with no warning. Authors who
  wrote fig-alt believed they had an accessible description and did not.

Behavior changes worth reviewing

#| in a mermaid fence is no longer a cell-option marker. Deliberate
(Q1 parity; q2 is in 0.* and accepting both would teach that #| is
universal), but it is a visible break: # is not a mermaid comment, so
leftover lines become diagram source and mermaid fails on them. Q-2-48 reports
this at the exact source line rather than leaving a silently broken diagram.

A diagram cell warns about options it cannot act on (Q-2-47), scoped to
diagram cells only. On an executable cell an unrecognized key is normally an
engine option (echo, eval, …), so warning there would fire on essentially
every real document. Q1 accepts theme and mermaid-format on mermaid cells
and q2 does not yet, so those warn today — DIAGRAM_OPTION_KEYS carries a note
to add theme when the mermaid theming strands land.

fig-alt on a non-diagram cell is now left in the body for the engine
instead of being consumed. Strictly better than the previous silent drop, and
for jupyter/knitr fig-alt is a real engine option.

Verification

cargo xtask verify (full, including the hub/WASM leg) passes on the rebased
base. No snapshot files changed anywhere in the workspace.

End-to-end through the binary, output inspected — e.g. a %%| fig-cap +
%%| fig-alt diagram with no label now emits:

<div class="quarto-figure quarto-figure-center">
<figure>
<pre class="mermaid">
flowchart LR
  accDescr: Two nodes connected by an arrow.
  E --&gt; F
</pre>
<figcaption>
A tiny flowchart.
</figcaption>
</figure>
</div>

The accessibility claim was verified against real mermaid 11.12.0 (the
pinned version) under jsdom, because both browser routes were unavailable in
the session: the injected line becomes <desc> inside the SVG with the SVG's
aria-describedby pointing at it, and a negative control confirms mermaid
rejects accDescr: placed before the diagram-type line — which is why the
directive is inserted after the first declaration line rather than at the top.

Not verified: presentation in an actual screen reader, and the q2 preview UI
in a live browser session.

Note for reviewers

main claimed Q-2-42 … Q-2-46 while this branch was in flight (#497), so the
two codes here were renumbered to Q-2-47 / Q-2-48 during the rebase. The
Phase 6 commit message still names the pre-rebase numbers; code, catalog,
tests and plan all use the final ones.

Follow-ups filed

• bd-vg8p5yoj — qmd-syntax-helper rule rewriting ```{mermaid}
  → ```mermaid. This is the other half of the Connect-docs story:
  all 33 diagrams there are brace-form and still render as source text until
  it lands. Cell options need no rewrite — Q1 documents already write %%|.
• bd-e3m3rkik — pre-existing, surfaced while reading the preview AST:
  because mermaid-render is excluded from preview, CodeBlockRenderTransform
  wraps mermaid blocks in copy-button chrome there that q2 render suppresses
  by transform ordering.

🤖 Generated with Claude Code

[posit-snyk-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.