Math syntax extension support

[lifthrasiir]

I personally needed this to move from Pandoc, so this particular syntax is modelled after Pandoc's math support.

Both $inline$ and $$display$$ forms are supported and (by default) rendered to <span class="math math-inline">inline</span> and <span class="math math-display">display</span> respectively. Custom renderers can be used to pre-render them as images or use different HTML classes (or even plain texts surrounded with \(\) or \[\] as required by Mathjax).

For inline math the opening dollar should not be followed by whitespaces and the closing dollar should not be followed by digits (to make $12 and $34 not math); display math has no such restrictions. In addition, display math can have embedded empty lines if the parent container can span multiple lines.

This syntax is notably different from Pandoc's in that non-escaped dollars in the inline math are always bad. Pandoc tries to understand complicated TeX tokens like $\text{the number of digits in $x$}$ but this implementation doesn't, so the example will render as two slices of inline math. It is recommended to use \(\) in dollars instead; unfortunately the support for \(\) in the JS-based TeX preprocessors is not yet widespread (at the time of writing, MathJax supports it while KaTeX doesn't).

Also tweaked build.rs to avoid rebuilding when only tests are changed (really, really annoying when you are playing with them).

[lifthrasiir]

(Hmm, should have been "the sum of elements in the top row times determinants for respective minors". Just in case.)

[ostrokach]

Since math is not part of the CommonMark spec, maybe it would be better if math support was provided as an extension (although I'm not even sure if that would be possible)?

Personally, I like GitLab-style math. I think that it is more idiomatic to Markdown, and it renders better on backends that do not support math.

There are also many other ways to represent math in markdown.

[CAD97]

Note that for block math, you can already get GitLab's syntax to work.

```math
5 + 5 = 10
```

becomes

<pre><code class="language-math">5 + 5 = 10
</code></pre>

If you load KaTeX (that's the API I know how to use) and run the following JavaScript at or after DOMContentLoaded

var maths = document.getElementsByClassName("language-math");
for (var i=0; i<maths.length; i++) {
    var el = maths[i];
    katex.render(el.innerText, el);
}

you end up with the following DOM:

<pre><code class="language-math"><span class="katex"><span class="katex-mathml"><math><semantics><mrow><mn>5</mn><mo>+</mo><mn>5</mn><mo>=</mo><mn>1</mn><mn>0</mn></mrow><annotation encoding="application/x-tex">5 + 5 = 10</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="strut" style="height: 0.64444em;"></span><span class="strut bottom" style="height: 0.72777em; vertical-align: -0.08333em;"></span><span class="base"><span class="mord">5</span><span class="mbin">+</span><span class="mord">5</span><span class="mrel">=</span><span class="mord">1</span><span class="mord">0</span></span></span></span></code></pre>

Indented

<pre>
 <code class="language-math">
  <span class="katex">
   <span class="katex-mathml">
    <math>
     <semantics>
      <mrow>
       <mn>5</mn>
       <mo>+</mo>
       <mn>5</mn>
       <mo>=</mo>
       <mn>1</mn>
       <mn>0</mn>
      </mrow>
      <annotation encoding="application/x-tex">5 + 5 = 10</annotation>
     </semantics>
    </math>
   </span>
   <span class="katex-html" aria-hidden="true">
    <span class="strut" style="height: 0.64444em;"></span>
    <span class="strut bottom" style="height: 0.72777em; vertical-align: -0.08333em;"></span>
    <span class="base">
     <span class="mord">5</span>
     <span class="mbin">+</span>
     <span class="mord">5</span>
     <span class="mrel">=</span>
     <span class="mord">1</span>
     <span class="mord">0</span>
    </span>
   </span>
  </span>
 </code>
</pre>

which, maybe surprisingly, renders fully properly (assuming KaTeX fully works in your browser).

The same works for inline <code class="language-math"> blocks, so all that would be needed from a markdown parser would be support for the translation of $`math`$ into <code class="language-math">math</code> instead of $<code>math</code>$.

There's a third argument to katex.render that can be given an options argument with {displayMode: true} if you want centered, display-mode math. So probably the best thing would be ```math to generate <pre><code class="language-math"></code></pre> per the spec, and inline syntax to use class="language-inline-math" or something.

I'm actually very fond of this syntax due to its trivial fallback to showing the raw commands, and reuse of the existing language-annotated block syntax. In theory you could have ```KaTeX and ```MathJax environments, which you treat differently.

The markdown engine only needs to support an extension for whatever inline syntax is chosen, and I think $`\LaTeX`$ is the best answer, subject to all the normal markdown rules for code blocking (so $`` math that includes a ` for some reason ``$ would be a valid code class="language-inline-code" block).

---

Formal(ish) proposal for this language-inline-math extension:

<inline-code-block> := (the spec as it exists currently) ;
<inline-math-block> := $ <no space> <inline-code-block> <no space> $ ;

<inline-math-block> is rendered the same as <inline-code-block>, except the produced <code> element will have a class attribute with the value of language-inline-math.

---

This seems simple enough and interests me enough that I'll try throwing something together for this over the weekend.

[marcusklaas]

Inline math would be excellent (and is long overdue)! Getting the syntax right such that it feels natural as LaTeX and markdown user proves to be tricky. I really like @CAD97's considerations, though I understand that dollar delimiters are falling out fashion in LaTeX for the exact reasons mentioned. Personally, I see merit in copying LaTeX's \( f(x) = y \) notation as it's familiar and shouldn't clash easily with other unintended uses. Perhaps we can restart the discussion at #6.

Unfortunately this PR is no longer compatible with the current design of pulldown-cmark and I'll close it for now.

[chlxt]

any progress on math extension support now? It's a key feature in engineering document writing.