How should we deal with math options/rendering/html?

[rowanc1]

I think there are a couple things to think about:

• Using markdown-it-texmath has a soft dependency on katex which I am pretty sure we do not want to bundle
  • Is the output the raw latex? Or should we have an option to actually put out the katex output (only requiring css)
  • My instinct at this stage is to leave it as latex (not rendered), similar to jupyter book at the moment
    • Note that this is different than the code, which is pre-parsed.
• We will have to have some defaults on what the math in markdown is configured as ($, \( \[, etc.)
  • I think the default is $..$, but overrides possible in options
• What is the html wrapper for math?

HTML Wrappers:

I think in JupyterBook/sphinx currently this is done:

Without a label:

<div class="math notranslate nohighlight">\[
\int_0^\infty \frac{x^3}{e^x-1},dx = \frac{\pi^4}{15}
\]</div>

With labels:

<div class="math notranslate nohighlight" id="equation-eqn-best">
<span class="eqno">(2)<a class="headerlink" href="#equation-eqn-best" title="Permalink to this equation">¶</a></span>\[
e = mc^2
\]</div>

And inline:

<span class="math notranslate nohighlight">\(x_{hey}=it+is^{math}\)</span>

[choldgraf]

the guiding principle that I think we've taken so far is to be as close to the Jupyter Notebook experience as possible. That way users aren't surprised when they do stuff w/ jupyter book vs. jupyter notebook. Does that help guide the decision-making here?

[rowanc1]

Thanks @choldgraf - I think that makes sense.

I have gone with default $s at this stage - similar to jupyter, looks like Jupyter also picks up things with \begin{equation}. And we also want to pick up {math}`` as a role and the directives as well.

I will get the basic functionality in through #5, and then we can always come back and fix/add things.

I am looking through markdown-it-texmath and it assumes that we render with katex and we can't template, without a full overwrite of the rules in markdown-it, so that might be something to contribute back to or spin off into a small sub-package. Not sure on your thoughts on that.

[choldgraf]

I don't have strong opinions on katex, not super familiar with it. I'm also really curious to see if MathJax 3 significantly improves on some of the downsides of MathJax (though it'll be a little while before we switch I assume, though I'll note that master on Sphinx now supports MathJax 3)

[rowanc1]

Just a quick follow up on this in #10 so far I have added a simple mathjax renderer to the demo, it is picking up standard math open/close which is set when rendering the html.

Right now I have gone with \( and \) for inline and \[ and \] for display. wrapped in span.math and div.math respectively. This is what is rendered not what is picked up from the html (which should be the things jupyter expects, although I haven't done the \begin{equation} yet).

[rowanc1]

I have now added amsmath through #25. Still outstanding here are the permalink html pieces.

[rowanc1]

I have gone into the unifiedjs ecosystem with this repository, and that has a much clearer separation of parse/ast-transformations/render. This is now in the render step, and can be done through existing plugins in this case, a user could choose either rehype-katex or rehype-mathjax and that would work with the (now standardized, mdast AST).

I will leave this open as a packaging issue, I think we need to define how we will export and support various versions of mystjs that either include or do not include these as dependencies. For example, the client-side code will likely not want to ship katex, but that is perfectly acceptable on the server side implementation.

[rowanc1]

We have gone the route of using the AST and then rendering in some other format (e.g. latex, jats, katex). I think there should be more information about rendering if you are just using the base parsers and html, but that is sufficiently tracked in #45.