Facilitate cross-referencing equations

[hturner]

As far as I can tell, the only way to cross-reference auto-numbered equations with litedown is via MathJax:

1. Configure MathJax to use automatic equation numbering. This can be done with an in-line script:

   <script>
   MathJax = {
     tex: {
       tags: 'ams'
     }
   };
   </script>

   that we can save in a file, say header.html. Alternatively create a mathjax-config.js file with the configuration.

2. In the YAML of the Rmd file, specify to use MathJax and include header.html:

   output: 
     litedown::html_format:
       options:
         js_math: "mathjax"
       meta:
         header_includes: header.html

   3. Use a raw LaTeX block to use an environment that will be auto-numbered, e.g.

      ```{=latex}
      \begin{equation}
      \begin{split}
      (a+b)^2 &=(a+b)(a+b)\\
      &=a^2+2ab+b^2
      \end{split}
      \label{eq:sample}
      \end{equation}

   4. Refer to it in an inline equation, e.g. Equation $\ref{eq:sample}$, where $\ref{eq:sample}$ will be replace by the equation number hyperlinked to an anchor on the equation.

Unfortunately this is not possibly with KaTeX (there is a longstanding issue on missing support for \label and \ref).

It would help those looking to cross-reference equations if litedown:

1. Configured MathJax to use automatic equation numbering by default, mirroring the default KaTeX behaviour.
2. Documented how to cross-reference equations, noting this is only supported by MathJax.

Is numbering/cross-referencing of Markdown equations on the roadmap? Something like the Quarto behaviour could be nice.

[yihui]

Numbering and cross-referencing equations are definitely trickier than other elements. It shouldn't be too hard to support MathJax. I need to do more research on KaTeX (the last two links in your post are missing; did you mean https://github.com/KaTeX/KaTeX/issues/2003?).

[hturner]

Yes, that's the one. I'll check and update my links.