Equation annotation proof of concept

This document presents, in Section 1.1, a proof-of-concept for MathJax equation annotation in HTML documents. The objective is to provide a way to co-locate, in long proofs, a math equation and a textual explanation of how it was derived from the equations preceding it. The source code is here. This feature is based upon the code annotation feature of Quarto.

I’d be very happy to get feedback on this feature, particularly for the points discussed in Section 1.2.4. Please or discuss it on the quarto github.

Status of the project described in Section 1.2. This is version 0.1 of this project. All features are subject to change before a stabilized version is released. The objective is to release this as:

  • a Quarto lua filter
  • standalone JS + CSS for HTML styling

Example

Below we have an example of the "side" annotation style: hover, click or focus on equation number.

\[\begin{align} A &= \int B \label{eq-1} \\ &= \sum C \label{eq-2} \\ &= \frac{D}{2} \label{eq-3} \\ &= E \label{eq-4} \\ &= \int F \label{eq-5} \\ &= G \label{eq-6} \\ &= H \label{eq-7} \\ \end{align}\]

Eqs. \eqref{eq-1}-\eqref{eq-2}
Applying Ross’s happy trees theorem, one happy little accident at a time. Ever make mistakes in life? Let’s make them birds. Yeah, they’re birds now.
Eqs. \eqref{eq-3}-\eqref{eq-5}
Expanding the integral and simplying terms together.

Below we have an example of the "bottom" annotation style: hover, click or focus on the blue text to highlight the corresponding equations.

\[\begin{align} A &= \int B \label{eq-11} \\ &= \sum C \label{eq-12} \\ &= \frac{D}{2} \label{eq-13} \\ &= E \label{eq-14} \\ &= \int F \label{eq-15} \\ &= G \label{eq-16} \\ &= H \label{eq-17} \\ \end{align}\]

Eqs. \eqref{eq-11}-\eqref{eq-12}
Applying Ross’s happy trees theorem, one happy little accident at a time. Ever make mistakes in life? Let’s make them birds. Yeah, they’re birds now.
Eqs. \eqref{eq-13}-\eqref{eq-15}
Expanding the integral and simplying terms together.

Current status of the project

Features

  • HTML + JS + CSS for bottom styling of equation annotation
  • HTML + JS + CSS for side styling of equation annotation

Usage

To add equation annotations to a document:

  • write a HTML document with Latex math rendered using MathJax
  • label the equation(s) you want to annotate with the \label{LABEL} latex command
  • write a dl element with class mathjax-code-annotation
    • style contained dd elements with a colon-separated list of labels data-annotation-target-ids="LABEL1;LABEL2"
    • modify JS script to use "bottom" or "side" styles
    • dd element inner HTML is used as is; or hidden
    • dt element inner HTML is used as is, or as a descriptive tooltip

Document lifecycle

  1. HTML is received by browser.
  2. JS script modifies MathJax config.
  3. MathJax transforms raw math into MathMajx MathML.
  4. JS script runs:
    1. Modifies MathJax renders of \ref and \eqref: remove links and tabindex.
    2. Inserts a highlighting div inside of the MathJax render of annotated equations.
    3. Adds a tippy event listener to trigger the annotation.

Open questions

  1. Improve UI/UX for standard user?
    • currently, interactive elements are highlighted with $link-color and cursor: pointer
  2. Improve CSS:
    • make code highlight-styling use appropriate variables instead of static
    • other?
  3. Improve accessibility? (aria attributes? Other?)
    • for highlight?
    • for interactive elements?
    • make sure not to interfere with MathJax
  4. Somehow, the integration in the MathJax lifecycle is not correct.
    • currently, I set the div after the MathJax pageReady hook
    • surprisingly, the MathML exists but does not have the correct size
    • the div is resized on show so it doesn’t matter
    • contrary to quarto, I don’t resize the div when the window is resized in my tests, this works fine
  5. Is the DOM manipulation of the MathJax components ok?
    • highlight div is integrated inside the MathJax MathML
    • tippy is attached to highlight div

Todolist

  • further integrate into quarto/pandoc markdown to HTML pipeline
  • fix markdown syntax for equation annotation
  • how to forward quarto/pandoc yaml options to JS script
  • proposal for latex styling (definition list as in HTML?)