referencing equations inside $$ \begin{align} environment

[HelenaLC]

Bug description

I am struggling to label multiple equations placed within $$ \begin{align} ... \end{align} $$.

This works flawlessly...

$$
\begin{align}
a &= 0+1 \\
b &= 2+3 \\
c &= 4+5
\end{align}
$$ {#eq-abc}

see @eq-abc.

...but neither of these work:

$$
\begin{align}
a &= 0+1 \label{eq:a} \\
b &= 2+3 \label{eq-c} \\
c &= 4+5 {#eq-d}
\end{align}
$$

I tried various other versions of Quarto and/or LaTeX syntax, but couldn't achieve the desired results: To have multiple numbered (and cross-referenceable) equations placed within an align-block.

Any suggestions would be greatly appreciated! And, it would be nice to have such an example included in the Equations sections of the Technical Writing documentation here.

Software:

• Quarto version 1.1.168
• macOS Monterey version 12.2
• RStudio IDE version "Prairie Trillium" Release
  (1db809b8, 2022-05-16) for macOS

Checklist

• Please include a minimal, fully reproducible example in a single .qmd file? Please provide the whole file rather than the snippet you believe is causing the issue.
• Please format your issue so it is easier for us to read the bug report.
• Please document the RStudio IDE version you're running (if applicable), by providing the value displayed in the "About RStudio" main menu dialog?
• Please document the operating system you're running. If on Linux, please provide the specific distribution.

[justanothergithubber]

Hello there, if you work with only HTML and PDF, I have the following (probably temporary) workaround:

---
format:
    html: default
    pdf: default
---
\begin{align}
    a &= 0+1 \tag{A}\label{eq:a} \\
    \begin{pmatrix}
        x \\ x \\ x \\ x \\ x \\ x \\ x
    \end{pmatrix} &=
    \begin{pmatrix}
        x \\ x \\ x \\ x \\ x \\ x \\ x
    \end{pmatrix} \notag \\
    b &= 2+3 \tag{B}\label{eq:b} \\
    \begin{pmatrix}
        x \\ x \\ x \\ x \\ x \\ x \\ x
    \end{pmatrix} &=
    \begin{pmatrix}
        x \\ x \\ x \\ x \\ x \\ x \\ x
    \end{pmatrix} \\
    c &= 4+5 \tag{C}\label{eq:c} \\
    \begin{pmatrix}
        x \\ x \\ x \\ x \\ x \\ x \\ x
    \end{pmatrix} &=
    \begin{pmatrix}
        x \\ x \\ x \\ x \\ x \\ x \\ x
    \end{pmatrix}
\end{align}
See Equation \eqref{eq:a}. See Equation \eqref{eq:b}. See Equation \eqref{eq:c}.

If you render this, the HTML should produce references to all 3 tagged equations without issue. If you render PDF, note that the align environment automatically numbers each line. You can add \notag to each equation you want to have no tag, or you can use align* instead. Note that there is no outer $$ in this case. (in case it wasn't obvious, the repeated x blocks are to add vertical space to show that the cross-refs go to the right vertical place)

I do not expect this to remain permanently usable, but for now it should work.

EDIT: I think some interesting background into how raw LaTeX is written in .qmd can be found here

[mattocci27]

Are there any workaround for MS word documents?

[abudden]

The workaround that uses \label and \eqref is probably better with \ref:

\begin{align}
a & = b + c \label{eq1} \\
c & = d + e \label{eq2}
\end{align}

Referring to equations \ref{eq1} and \ref{eq2}...

The difference is that \eqref renders the equation number as (1) where as \ref renders it as 1. Arguably the \eqref version is better, but it won't match the other equations in the document (ref #2439).

[eeholmes]

tldr; For LaTeX users wanting complex math in both html and PDF using the same Quarto file: 1) Add a mathjax.html file (instructions below) to turn-on equation numbering and only use LaTeX equation environments (not $$). 2) For referencing, only use \label{} and \eqref{} or \ref{}. Do not use (#eq-) and @eq- for referencing. Pandoc (and MathJax) knows LaTeX so all your fancy equations should work if you do 1 and 2.

---

\begin{align}
a & = b + c \label{eq1} \\
c & = d + e \label{eq2}
\end{align}

will not render equation numbers in html. You could add \tag{1} but then you lose the autonumbering feature. The problem is that by default MathJax is set up to not show the numbers. Why the MathJax folks choose the opposite default as LaTeX makes no sense but that is what they did. So you have to turn on numbering. Sadly how you do this depends on the version of MathJax and the documentation is not 100% helpful. 🤯🤯

Here is how to turn on numbering with the MathJax v3+ file that Quarto is using.

mathjax.html

<script>
  MathJax = {
    tex: {
      tags: 'ams'  // should be 'ams', 'none', or 'all'
    }
  };
</script>

For MathJax v2.7, the config uses MathJax.Hub.Config so search for that if this doesn't work with the MathJax js file you are using. Note MathJax v2.7 was replaced with v3 in 2017-2018, but you will still see many websites loading MathJax v2.7.
:
_quarto.qmd yaml looks like this now

---
title: "test"
format:
  html:
    include-in-header: mathjax.html
  pdf: default
---

Now this shows your autonumbers in both html and pdf output.

\begin{align}
a & = b + c \label{eq1} \\
c & = d + e \label{eq2}
\end{align}

Something to keep in mind is that the Quarto equation numbering is incompatible with LaTeX equation environment numbering in html but works fine in PDF. Weird. Just don't use the (handy) @eq-eq1 for references, instead use \eqref{} or \ref{}, because Pandoc doesn't figure that out for the equation environments. Look at this example that mixes $$ $$ with equation environments (\begin{align}).

$$
S_n = \frac{X_1 + X_2 + \cdots + X_n}{n}
      = \frac{1}{n}\sum_{i}^{n} X_i
$$ {#eq-eq1}

\begin{align}
a & = b + c \label{eq2} \\
c & = d + e \label{eq3}
\end{align}

$$
S_n = \frac{X_1 + X_2 + \cdots + X_n}{n}
      = \frac{1}{n}\sum_{i}^{n} X_i
$$ {#eq-eq4}

Produces this in html:

Produces this in PDF

If you only need to render to both html and PDF, then I would say never use $$ $$ and @eq- for equations. Stick to the equation environments (which btw is what LaTeX users would normally use) and use\eqref{} and \ref{}. If you need to render to word though....only $$ $$ is recognized; equations in equation environments are completely removed! 🤯

I tested with Quarto docx format and RMarkdown officerdown::rdocx_document format and both showed the same behavior. I don't know how Pandoc is doing the markdown to Word XML (I assume) conversion but seems like the non-recognizing LaTeX equation environments is at a low level. But I also didn't search for a "equation to image" option, which would allow Pandoc to create the equation imagew via LaTeX and bypass the Word Equation engine. I don't know if that is a thing, but that is how I would solve equations in Word docs created with Quarto/RMarkdown.

A note re \eqref{}. Here is how to redefine it for PDF output. I don't know how to do this for html. Pandoc knows \eqref{} so there must be a way to redefine for html. Note, Pandoc will understand \newcommand{} and \renewcommand{} for html but weirdly in html the new definition is recognized only in math environments, like $ $. Anyhow for PDF output this will work

  pdf: 
    include-in-header: 
      text: |
        \renewcommand{\eqref}[1]{Equation~\ref{#1}}

[eeholmes]

Note I tried a mathjax.html file with both ways of turning on numbering, and it still worked. So this file may be a more robust way to turn on numbering since it will work with more versions of MathJax (I think).

<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: { equationNumbers: {autoNumber: "AMS"} },
  tex2jax: {inlineMath: [ ['$','$'], ["\\(","\\)"] ]}
});
</script>

<!-- This is what works with Quarto -->
<script>
  MathJax = {
    tex: {
      tags: 'ams'  // should be 'ams', 'none', or 'all'
    }
  };
</script>

But weirdly with the MathJax file that RStudio Rmd files loads (v2.7 from 2017), the line up of the equations numbers changes. Here is the format spec in the Quarto file:

format:
  html:
    include-in-header: mathjax.html
    html-math-method:
      method: mathjax
      url: "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"

How do you know what version of MathJax that a js file is? Paste the url in the browser and look at the top of the js file. The info on the version of MathJax will be there.

For comparison, here is the MathJax js file that Quarto is using by default is:

"https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"

[pglpm]

@eeholmes Thank you so much for the mathjax config scripts and the detailed explanations.

One question: the Mathjax 3.2 doc pages use window.MathJax at the beginning of configuration files. Is this equivalent to the MathJax at the beginning of the config scripts above? Or are these two completely different things? Cheers!

[ikosmidis]

Just landed on this thread, and here is a proposal using the aligned environment within $$ ... $$.

$$
\begin{aligned}
a &= 0+1 \\
b &= 2+3 \\
c &= 4+5
\end{aligned}
$$ {#eq-abc}

see @eq-abc, or ([-@eq-abc]).

This works with default settings with correct labels in both PDF and HTML ( and I guess word!) and does not require any MathJax hacking.

Useful thing is that

format:
  html:
    crossrefs-hover: true

will display referenced equations on hover in HTML (and PDF, depending on your PDF reader), which is handy with long technical content.

[asmaier]

It should be noted that using aligned instead of align won't work. This document test.md

---
title: "test"
format:
  html:
    include-in-header: mathjax.html
---

$$\begin{aligned}
a & = b + c \label{eq2} \\
c & = d + e \label{eq3}
\end{aligned}$$

Refer to `\eqref{eq2}`{=latex} and `\eqref{eq3}`{=latex}.

will render using quarto preview test.md like

Instead of two equations with two labels mathjax counts them as one.

Why is this relevant? If one starts with the following latex file test.tex

\documentclass[12pt,a4paper,twoside]{book}
\usepackage[intlimits]{amsmath}	

\begin{document}

\begin{align}
a & = b + c \label{eq2} \\
c & = d + e \label{eq3}
\end{align}

Refer to \eqref{eq2} and \eqref{eq3}.

\end{document}

and converts it to markdown via quarto pandoc --wrap=preserve -t markdown -f latex+raw_tex -o test.md test.tex then pandoc will unfortunately convert the align environment into an aligned environment (because of this issue jgm/pandoc#4104) and one ends up with a markdown file as shown above.

[ikosmidis]

My solution is correct for just a single label for all aligned equations in a single display. I tend not to need more than one label, mainly because I avoid more than three equations in a single display, and then I can always say the first / second / third / etc. equation/expression/ etc. in XYZ.

Labelling more than 1 equation in a single align display in the current quarto version seems impossible without the Mathjax hacks in previous responses. But with those, many nice goodies that quarto provides and guarantees on the outputs between formats may be lost.