I have a few things to talk about here. This is a bit long so I will provide some sections, treat this as a blog post if you want.
markdown-it-math: My thoughts 10 years ago
I wrote the markdown-it-math plugin 10 years ago as well as an AsciiMath dialog called mathup (then called Ascii2MathML) with the main purpose of being a good fit for markdown documents. I kept the markdown-it plugin as abandoned over the last 7 years but just returned to it earlier this month. Here are a few things I have observed at the time, and how my opinion on this has changed with it.
When I first wrote mardown-it-math I had 3 predictions on math in markdown in mind:
- AsciiMath is a good fit for markdown.
- People will want to math delimiters to behave like code delimiters.
- MathML will be the way to render math on the web, with full browser support just around the corner.
I was wrong on all these counts. The one I was closes to was (3) except browser support came 10 years later, and even then MathJax and KaTeX may still be a more popular way to render math on the web. But number (1) and (2) came as more of a surprise for me.
AsciiMath instead of LaTeX
I defaulted markdown-it-math to my AsciiMath dialect thinking that people that want to write math in LaTeX would do so in LaTeX, and that people writing markdown documents might not know how to write LaTeX beyond the most basic expressions. And that a document format which emphasizes an easy to read markup would surely want to write math expressions which was also easy to read. This was wrong. Almost all markdown environment that now support math, do so with LaTeX and almost none AsciiMath.
I also defaulted the math delimiters to double dollars ($$) for inline math and triple ($$$) for block. This was so authors wouldn’t unintentionally include math expressions, and to match the triple backticks of fenced code blocks. But to my surprise nobody liked this, and almost every user that I know of changes these defaults. What is more surprising is many users were asking for LaTeX style delimiters \(…\) and \[…\] that they wanted to inline display math with the block delimiters (which makes info strings impossible):
\[ \sum_{n=0}^{\infty} \frac{1}{2^n} \]
and even for block math to break in a middle of a paragraph:
Here is some text \[ \sum_{i=0}^{\infty} \frac{1}{2^n} \] and this is
the next paragraph.
But that example not common, most people want to do something like this:
Here is some text
$$ \sum_{i=0}^{\infty} \frac{1}{2^n} $$
and this is the next paragraph.
In comparison this is how I prefer to write markdown:
Here is some text
$$$
sum_(i=0)^oo 1 / 2^n
$$$
and this is the next paragraph.
Lessons learned
When I returned to markdown-it-math I decided I should probably default to how most people want to use it so I changed the default delimters to $…$ for inline math (also support gitLab’s and GitHub’s $`…`$ by default) and $$…$$ for display math. I also kept support for writing display math inline with the delimiters (but they have to start and end on a newline). I still default rendering with my AsciiMath dialect which renders to MathML, but also documented prominently how to use Temml instead, which is a LaTeX to MathML rendering engine. We will see if this proves popular.
The current state of how math is written and delimited is a bit undecided in my opinion. LaTeX seems to have won out, although that might be simply because people might not know there are other options. Single dollar for inline delimiters and double for block are also obvious winners, however:
$$ block math expression $$
vs,
$$
block math expression
$$
$$ infostring
block math with infostring
$$
is still undecided. As is:
$$inline math with $ a dollar$$
and
$$$
$$block math$$
$$$
Prettier js will do some weird stuff with your math delimiters and does not like them thicker but the GitHub’s syntax highligher likes to highlight math inside dollars just like they were code spans or fenced code blocks. Inconsistently GitHub’s math rendering engine will not render all the math it highlights as such in their syntax highlighter.
Going forward
In addition to returning markdown-it-math to maintenance, I wrote a couple of more markdown-it plugins for rendering math, follow the commonmark spec for backtick code spans and fenced code blocks named markdown-it-mathspan and markdown-it-mathblock. These are copy-pastes of markdown-it’s codespans and fenced code blocks respectively.
My hope is that going forward people will want to write math in markdown, like they write other markdown, but not suddenly context switch to TeX when it comes to math. Realistically I don’t think that will be the case. I did compromise here though in having the thinner dollar variants as the default, while offering a thicker variant with an minDelims option (defaulting to 1 and 2 for inline and block math respectively). This seems consistent with what GitHub’s syntax highlighter thinks is math.
Additionally, instead of rendering straight to MathML by default, I decided that it might be better to render to custom elements, which in turn may render to the final MathML. For that I also wrote a custom element wrapper around Temml and (by default) sniff the custom element registry whether to render to a <math-up> element or a <la-tex> element. I have not yet concluded on whether that was a good idea or not. But I have high hopes for this approach.
What I discovered while writing both the <la-tex> custom element, as well as markdown-it-blockmath plugin is that infostrings may be quite useful for math expressions, not necessarily to tell which renderer to use (I honestly don’t think that is an issue) but to specify fine tuning to the final renderer such as defining macros in a preample, adding labels, telling which decimal mark to use, etc.
# Title of document
$$ preample
\def\P{\mathbb{P}}
\def\pdf{\mathrm{pdf}}
\newcommand\d[0]{\operatorname{d}\!}
$$
We compute $\P(X)$ with
$$ label=eq1
\P(X) = \int_(x \in \R) \pdf(x) \dx
$$
This is impossible to write in the current (and probably all future) version of markdown-it-math.