Skip to content

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

Open
Open
FR: add support for div syntax in block equations, and span syntax in inline equations#13019
Assignees
cscheid
Labels
crossrefenhancementNew feature or requestqmd-syntaxIssues related to the syntax of qmd documents.
Milestone
Future

Description

@KleinWurm
KleinWurm
opened on Jul 1, 2025

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

Activity

  1. KleinWurm
    added
    bugSomething isn't working
    on Jul 1, 2025
  2. mcanouil
    added
    crossref
    mathany issue related to math support in specific formats
    and removed
    mathany issue related to math support in specific formats
    on Jul 1, 2025

  3. mcanouil commented on Jul 1, 2025

    @mcanouil
    mcanouil
    on Jul 1, 2025
    Collaborator

    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
:::

  4. mcanouil commented on Jul 1, 2025

    @mcanouil
    mcanouil
    on Jul 1, 2025
    Collaborator

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

  5. mcanouil commented on Jul 1, 2025

    @mcanouil
    mcanouil
    on Jul 1, 2025
    Collaborator

    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
$$
:::

  6. KleinWurm commented on Jul 1, 2025

    @KleinWurm
    KleinWurm
    on Jul 1, 2025
    Author

    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?

  7. cscheid commented on Jul 1, 2025

    @cscheid
    cscheid
    on Jul 1, 2025
    Member

    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.

  8. cscheid
    added
    enhancementNew feature or request
    and removed
    bugSomething isn't working
    on Jul 1, 2025
  9. cscheid
    self-assigned this
    on Jul 1, 2025
  10. cscheid
    added this to the Future milestone on Jul 1, 2025
  11. cscheid
    added
    qmd-syntaxIssues related to the syntax of qmd documents.
    on Jul 1, 2025

  12. cscheid commented on Jul 1, 2025

    @cscheid
    cscheid
    on Jul 1, 2025
    Member

    @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.

  13. cscheid
    changed the title [-]Equation cross-reference fails when using Div Syntax instead of Float Syntax.[/-] [+]FR: add support for div syntax in block equations, and span syntax in inline equations[/+] on Jul 1, 2025

  14. cscheid commented on Jul 1, 2025

    @cscheid
    cscheid
    on Jul 1, 2025
    Member

    Documentation PR is up.

  15. KleinWurm commented on Jul 1, 2025

    @KleinWurm
    KleinWurm
    on Jul 1, 2025
    Author

    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.

    You are right, the doc describes very clearly the behavior of "float cross-references". I was not aware that Equations are not floats, thanks for making this clear!

    I overlooked the complexity behing the second "improvement" and would like to say thanks for your explanation.

  16. KleinWurm
    closed this as completedon Jul 1, 2025
  17. cscheid
    reopened this on Jul 1, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

crossrefenhancementNew feature or requestqmd-syntaxIssues related to the syntax of qmd documents.

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions