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.

[yihui]

After fully reading https://github.com/KaTeX/KaTeX/issues/2003, I feel hopeful to number and cross-reference equations with KaTeX.

It should be simple enough to configure MathJax for litedown by default. I'll do that next week. Thanks for the suggestion and guidance!

[yihui]

Phew, all done. Add a \label{eq:*} (and optionally a \tag{}) to an equation, and then use @eq:* or @eqn:* to cross-reference it. Both MathJax and KaTeX should work out of the box. No extra config is required.

Honestly speaking, I don't feel comfortable with my hacks since I don't think the way that I scan labels and tags is not robust: https://github.com/yihui/misc.js/blob/main/js/render-katex.js but that's my best effort for now, given all the constraints from KaTeX. I'll post to https://github.com/KaTeX/KaTeX/issues/2003 and seek feedback when I have more time.

Something like the Quarto behaviour could be nice.

Actually litedown's cross-reference mechanism is more general than Quarto's. Anything can be numbered and cross-referenced in {litedown}, although the number of built-in cross-referenceable elements is small (section/figure/table/equation). I just spent a little more time on documenting it: https://yihui.github.io/litedown/#sec:cross-references (this is the link to latest dev version of the book, not intended to be shared widely, so I put the URL in code)