Implementing label, tag and eqref in KaTeX using a macro approach

There have been many user requests for implementation of \label and \eqref in KaTeX. It hasn't been implemented fully so far because of issues surrounding server rendering and numbered links.

Here's a possible workaround until (or if) it's finally implemented. (See also my non-macro solution.)

See more info below the demo.

[MACRO DEMO STARTS]

Demo: \label and \eqref using macro

Link to Eintein \eqref{eins}, and VolSolRev \eqref{volsolrev} and Vol2Curves \eqref{vol2curves} and first line \eqref{gat} or even the second line \eqref{got} and Imaginary \eqref{imag} and Calculus \eqref{calc}, Newton's Law \eqref{newtlaw}, but Newton's Second Law is not like this: \eqref{newtlaw2} and an equation with split \eqref{splitone2} and binomials \eqref{binom2}

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

A sprinkling of Euler: \begin{equation} \begin{split} e^{i\pi} + 1 &= 0 \\ e^{i\pi} &= -1 \end{split} \end{equation}

and imaginary: \begin{equation} i^2 = -1 \label{imag} \end{equation}

Einstein concluded (after considering Newton's 1st Law \eqref{newtlaw}): \begin{equation} E=mc^2.\label{eins} \end{equation}

Now, gather around, everyone, one with 2 labels: \begin{gather} \text{quantum}=b \label{gat} \\ e=\text{physics} \label{got} \end{gather}

the first line \eqref{gat} or even the second line \eqref{got} of that environment

Of course, he stood on the shoulders of giants, including Newton.

After allowing for imaginary numbers \eqref{imag}, we have an equation without labels or tags: \begin{equation} e^{i\pi} + 1 = 0 \end{equation}

Elsewhere, we'll see how to define the position, velocity and accelration vectors, at \eqref{rva_a}, but first we all need better column alignment: \begin{alignat}{2} 109&x+&3&y=2 \nonumber\\ 3&x+&125&y=4 \tag{alat} \end{alignat} and \begin{equation} \begin{split} \text{an} &= \text{equation} \\ &=\text{with}+\text{split} \label{splitone2} \end{split} \end{equation}

Newton's calculus allowed us to find the general equation for the volume of a solid of revolution for the area bounded by $y=f(x)$ and between $x=a$ and $x=b$, which is: \begin{equation} V_\text{rev} = \pi\int_{a}^b [ {f(x)} ]^2\,dx\label{volsolrev} \end{equation}

Extending volsolrev \eqref{volsolrev} to the case of rotating an area bounded by two curves, we get vol2curves:

\begin{equation} V_\text{rev} = \pi\int_{a}^b [ {y_2}^2-{y_1}^2 ]\, dx \label{vol2curves} \end{equation}

Here is an equation without labels or tags: \begin{equation} \frac{df}{dt}=\lim\limits_{h \to 0}\frac{f(t+h)-f(t)}{h} \end{equation}

Using \eqref{vol2curves}, the volume of the solid of revolution resulting from rotating the area bounded by $y_1=\sin^2(2x)$ and $y_2=\sin^2(x)$ between $x=1$ and $x=3$ is given by: \begin{align} V_\text{rev}&= \pi\int_{a}^b [ {y_2}^2-{y_1}^2 ]\,dx\nonumber\\ &= \pi\int_{1}^3 [ {\sin^2(x)}-{\sin^2(2x)} ]\,dx\nonumber\\ &= \pi(1/8 (2 \sin(2) - \sin(4) - 2 \sin(6) + \sin(12)))\nonumber\\ &\approx 1.0201 \label{calc} \end{align}

We can have a non-numbered environment with a label (which is pmat): \begin{pmatrix} a & b \\ c & d \label{pmat} \end{pmatrix} and we can have velocity \eqref{rva_v}.

We can have another non-numbered environment this time with a tag: \begin{Vmatrix} i & j \\ k & m \tag{Vmat} \end{Vmatrix}

Newton determined that :

\begin{equation} \boldsymbol{F}=m\boldsymbol{a} \label{newtlaw} \end{equation} and as an intelligent extension, we could have: \begin{equation} \boldsymbol{F_2}=m_2\boldsymbol{a_2} \label{newtlaw2} \end{equation} and further talked about position at time $t$, \eqref{rva_r}.

We don't necessarily use \eqref{pmat}, or to define the position vector $\boldsymbol{r}$, the velocity vector $\boldsymbol{v}$, and the acceleration vector $\boldsymbol{a}$ by \begin{align} \boldsymbol{r} &= x\boldsymbol{i}+y\boldsymbol{j}+z\boldsymbol{k},\label{rva_r}\\ \boldsymbol{v} &=\dot{x}\boldsymbol{i}+\dot{y}\boldsymbol{j}+\dot{z}\boldsymbol{k}, \label{rva_v}\\ \boldsymbol{a} &=\ddot{x}\boldsymbol{i}+\ddot{y}\boldsymbol{j}+\ddot{z}\boldsymbol{k}. \label{rva_a} \end{align}

But Einstein's idea in \eqref{eins} was a conjecture on acceleration \eqref{rva_a} until proof was found of time dilation effects \eqref{volsolrev}, pmatrices \eqref{pmat}, black holes \eqref{imag} and quantum physics \eqref{gat}.

Then again, most school children learn Newton's Law \eqref{newtlaw}, but Newton's Second Law is not like this: \eqref{newtlaw2}. He preferrred to work on calculus \eqref{calc}

Equations with missing items

These next two would mess up the counting if they came earlier in the page:

Here is an equation with label, but is missing a \nonumber: \begin{align} r&=\frac{a^2-c^2}{a+c\cos\theta}\\& =\frac{a^2(1-\frac{c^2}{a^2}\,)}{a(1+\frac{c}{a}\;\cos\theta)}\nonumber\\& =\frac{a(1-e^2)}{1+e\cos\theta}\nonumber\\& =\frac{k}{1+e\cos\theta}\label{ellippolar} \end{align}

This one has a tag, but is missing a \nonumber: \begin{alignat}{2} 109&x+&3&y=2 \nonumber\\ i&x+&77&j=2c \\ 3&x+&125&y=4 \tag{alat} \end{alignat}

Orphan eqref

Here's an orphan eqref for demo purposes: \eqref{wheresWally} and another \eqref{foo}.

[MACRO DEMO ENDS]

Further explanation

This macro solution works as follows:

  1. A KaTeX macro takes the label and adds it as an id to span.enclosing, nearby where the equation number tag appears.
  2. I've changed the id so it has a prefix "katex-lbl-" so there is less likelihood of clashes with autor's own id's on the page.
  3. If an environment contains a label, the script makes use of it for incrementing the eqrefNum variable, so the eqref links all have the correct numbers.
  4. If the label is in a numbered environment, the \eqref points to the number, otherwise the anchor text is the actual label (for example "pmat" in the demo)
  5. For numbering to work correctly, and for consistency when authoring, each line in a numbered environment either needs to contain a \label or a \nonumber.
  6. Where there is more than one label in an environment, the links to those labels point back to the whole environment (spans with id's are wrapped within spans with id's). While this is not KaTeX's default behaviour, it's better usability.
  7. In MathJax, links point to the actual number of a numbered environment. This is annoying, as you always have to scroll up to see the whole equation, so the numbered line can finally make sense. I feel linking to the environment is better usability.
  8. The \eqref{...} expressions are handled by this script, not by KaTeX, so that we get numbered links, not text links.
  9. Links are just ordinary <a> tags using KaTeX font. Making these into math objects is overkill.
  10. We can have the environment within <p> tags, or outside, no change from normal KaTeX behaviour.

The code