FR: add support for div syntax in block equations, and span syntax in inline equations

[KleinWurm]

I have:

• searched the issue tracker for similar issues
• installed the latest version of Quarto CLI
• formatted my issue following the Bug Reports guide

Bug description

It seems that using Div Syntax around equations breaks the cross-reference.

Steps to reproduce

---
format: html
---

Cross-reference for @eq-float works but not for @eq-div.

$$
E=mc^2
$${#eq-float}

::: {#eq-div}
$$
E=mc^2
$$
:::

Actual behavior

The document renders with a warning: WARNING ([path]/Quarto/share/filters/main.lua:14000) Unable to resolve crossref @eq-div

Expected behavior

I expected the cross-reference to render just like the one specified using the float syntax.

Your environment

• IDE: RStudio 2025.05.0 Build 496
• OS: Windows 11

Quarto check output

Quarto 1.7.31
[>] Checking versions of quarto binary dependencies...
      Pandoc version 3.6.3: OK
      Dart Sass version 1.85.1: OK
      Deno version 1.46.3: OK
      Typst version 0.13.0: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
      Version: 1.7.31
      CodePage: 1252

[>] Checking tools....................OK
      TinyTeX: v2023.03
      Chromium: (not installed)

[>] Checking LaTeX....................OK
      Using: TinyTex
      Version: 2022

[>] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Source: Windows Registry

[>] Checking basic markdown render....OK

[>] Checking Python 3 installation....(None)

      Unable to locate an installed version of Python 3.
      Install Python 3 from https://www.python.org/downloads/

[>] Checking R installation...........OK
      Version: 4.5.1
      knitr: 1.50
      rmarkdown: 2.29

[>] Checking Knitr engine render......OK

[mcanouil]

FYI, it's not about math.
It's about the use of eq- prefix for something that isn't math.
The code below will show the same result.

---
format: html
---

Cross-reference for @eq-div.

::: {#eq-div}
whatever
:::

[mcanouil]

To me, it's not really a bug as the prefix is currently tied up to equation as documented:

• https://quarto.org/docs/authoring/cross-references.html#equations

[mcanouil]

With the custom float cross-reference, you can still do what you want but without the equation number next to the equation because that is done by the math library being used.

---
format: html
crossref:
  custom:
    - kind: float
      reference-prefix: Equation
      key: eq
---

Cross-reference for @eq-float works but not for @eq-div.

$$
E=mc^2
$${#eq-float}

::: {#eq-div}
$$
E=mc^2
$$
:::

[KleinWurm]

I understand that this might not be a bug; with your answer it seems more like an unexpected behavior from my user perspective that could be solved by adjusting the doc.

Maybe this could be relabelled as potential future enhancement?

[cscheid]

Let me try to unpack here. If you read the first section of the documentation we're discussing, you will find the following:

Cross-referenceable figures, tables and code listings are known as float cross-references. Floats can appear in the rendered document at locations other than where they are defined, i.e. they float, and usually have captions.
Along with compact syntax for the most common uses of cross-references, Quarto also provides a more general div syntax for declaring floats that can be cross-referenced.

These are the first two paragraphs of the section. They describe (in my opinion, fairly clearly) the behavior of "float cross-references". Equation cross-references (along with many others) are not floats. This is described implicitly (in the sense that since equations clearly do not float, they shouldn't be assumed to work with div syntax), but we do not explicitly state in the documentation that equations (and theorems, lemmata, etc) are not floats. This first improvement suggestion we can and should make.

The second improvement that you're requesting is the ability for block syntax to be used in equations.

Here, we have to be careful: equations can appear inside a paragraph (i.e, in inline syntax), or in a paragraph by themselves, (i.e. in block syntax). We can't say "div syntax can be used for equations", because divs are blocks. We instead would have to come up with a new block syntax for block equations ("display math"), and a different, new inline syntax for inline equations ("inline math"). That is a significant complication, and not something we can promise to do in any near future timeframe.

[cscheid]

@cderv, @gordonwoodhull, @vezwork, @mcanouil: FYI I created a qmd-syntax label. Feel free to use it for triaging issues that relate to how we parse the text in .qmd files into Quarto's AST.