State of Quarto for Mathematics

[FelixBenning]

Description

In the past week(s) I attempted to evaluate whether or not Quarto was suitable for mathematical work. Here I want to summarize the main issues I found and afterwards add a wishlist of "nice-to-haves".

It would be great if the maintainers were able to provide some updates/information on the priorization of these issues - especially with respect to the reference system. Because the workarounds for the reference system typically go against the native Quarto syntax and would often cause a lock-in effect because it would cause a lot of work to change things back.

Bugs

• Inconsistent Proof labeling (Proof name behaves different in html and pdf #12928)

Issues (Things that LaTeX can do but Quarto can't)

• Global TeX Macros

  \newcommand macro definitions are not easily introduced in both html and tex, see

  • Global TeX Macro file #12838 (workaround available, pain: 🟢 )

• The Reference System

  • Referencing individual lines in align(ed) math equations. (workarounds available, pain: 🟠 )

    • referencing equations inside $$ \begin{align} environment #2275 first added by @cscheid to the milestone v1.2 in 2022 and then repeatedly pushed back until it ended up as v1.5 and Future in May 2024. v1.5 has passed - does this mean this issue was given up upon?
    • Add a referencable latex align equation #12873

  • More customizable theorem environements, specifically theorem groups with shared counters that use the same numbering (no real workaround available 🟠 )

    • StackOverflow: Shared counter for exercises, examples, etc.
    • Is there a way to wrap theorems and the linke in tcolorboxes when the output is PDF? #7313

    There has been an extension ute/custom-numbered-blocks to work around this issue. But apparently changes to the reference system from v1.2 to v1.3 broke this extension and resulted in a wontfix Cross referencing block titles no longer works with quarto > 1.3.4x ute/custom-numbered-blocks#9

• Sync Code to Preview 🔴 : SyncTeX is an amazing tool that seems to store crossreference data in a file. The LaTeX Workshop extension for VSCode alows users to Cmd + Click on text in the pdf to be thrown to the LaTeX code. Or similarly jump from the code to the place in the pdf. Synctex is similarly integrated with other editors. This is something that does not exist for Quarto. To my knowledge this does not even exist for html preview in VSCode so this may be very difficult to implement. Maybe somehow store the line number as a class attribute of html elements?

Nice to have (Things that LaTeX cannot do)

• Collapsible Proofs: This would be an obvious improvement over LaTeX that would provide a tangible benefit for moving to Quarto if none of the Quarto specific features are used.

  • Collapsible Proofs out of the box #12878
  • Make proofs collapsible in HTML #5272

  Available Extensions that do something similar:

  • ute/custom-numbered-blocks implements this, but is broken since v1.3
  • sun123zxy/quarto-callouty-theorem wraps theorems and proofs in callout boxes, issues:
    • callout boxes wrap the theorem, resulting in two titles and references showing only the inner part
    • callout boxes stand out too much, a visually more muted approach would be nice especially for Proofs.

[mcanouil]

Have you looked at the Visual Editor (part of RStudio and Positron/VSCode via the extension)?

[FelixBenning]

That is indeed interesting and something I missed about the extension. I just tried it: An issue is that the global TeX macros are not rendered because the \newcommand include mechanism apparently does not work with this. It does with the normal preview though. It also chooses to rewrite the entire file apprarently and uses non-descriptive tags for footnotes for example.

[mcanouil]

As several Markdown syntaxes can lead to the same thing, the Visual Editor has to use one syntax.
Under the hood, the Visual Editor uses Pandoc to standardise the Markdown.

[FelixBenning]

I suppose, but [^semantically-relevant-tag] replaced with [^usage-23] is not ideal.

[mcanouil]

FYI, the repository for the VSCode extension and the Visual Editor: https://github.com/quarto-dev/quarto/issues
The Visual Editor is a tool on its own (but not a stand alone) embedded in other tools such as the VSCode extension.