Yet another request for equation reference

Before requesting a feature, please search for existing issues.

Is your feature request related to a problem? Please describe. Equation labeling and reference (\label and \eqref) are handy features in technical and scientific writing. The features have been requested in issue #350, #571 and #2003, but little further progress seems to be made.

Describe the solution you’d like:

The full \label and \eqref requires three things:

• \tag to create equation tags, which is already implemented
• \label to give a label to an equation, and to automatically add a \tag to that equation
• \eqref to refer to the equation

A possible reason that the last two features are not implemented may be that what exactly the number \eqref displays cannot be determined by a single scan of the page: in LaTeX you need to compile the file twice to get everything done, causing performance overhead. (I’m not familiar with the inner implementation of KaTeX so sorry for anything inaccurate in my comments.)

A more practical solution may be to implement \label first: KaTeX keeps a global counter, and when KaTeX meets a math block with \label{the-label}, the counter +1 and a \tag is inserted, and an anchor with an id like katex-eq-the-label is also inserted.

\eqref can then be implemented in a progressive enhancement manner:

1. The costless approach is to forget about \eqref and let users just use a hyperlink with the target #katex-eq-the-label and specify the hyperlink text by themselves. In this way equations themselves are automatically numbered, but users still have to check the number of an equation when refering to that equation.
2. A slight enhancement is to include \eqref in a very restricted manner: for example, \eqref is included but the only legit way to use it is $\eqref{the-label}$ with nothing else in the block. KaTeX ignores these \eqrefs when displaying math, and does a fast second pass to find all $\eqref{the-label}$ and replace them with hyperlinks whose targets are the labels and whose hyperlink texts are the numbers of equations. In this way the performance may still be acceptable because the second pass doesn’t start the whole math engine. This should cover most of the equation reference demands.
3. Maybe one day the full \eqref is implemented.

Describe alternatives you’ve considered: Create a markdown-it plugin that does the same work; this is outside the discussion about KaTeX itself, though.

[ronkok]

@wujinq You are correct in that \ref requires a pass through the entire document.

As it happens, I’ve already implemented \label and \ref in my new library, Temml. I could back-port the work from there into KaTeX. Before I start work, I’d like to hear from others what they think about how the implementation works.

In order to support \label and \ref, I exposed a new function, postProcess() . It does the pass through the entire document noted above. A website administrator who wanted to support \ref would have to make a call to katex.postProcess() after all the calls to katex.render are complete. The source code in a web page might look something like this:

const macros = {};
for (let element of mathElements) {
    katex.render(element.textContent, element, { macros });
}
katex.postProcess(document.body);

For the other contributors here, please let me know what you think of that approach. If it is acceptable, I can do the back-port.

[N0rbert]

\begin{equation}
  g\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
\label{binom2}
\end{equation}

still does not work.