I've compiled a neat little comparison on what math in Markdown can and can't do on different platforms. TLDR: Don't use GitHub if you're serious.

An interesting take, thanks for the input! As a layman (pretty much), I had always a bit frowned upon reST since I never got used to syntax. That was probably because Markdown was already so popular when I started using it.

One little remark: You can still have highlighted math code blocks in gh's Markdown. The lang here is ```latex. Anyway, I see this might not be satisfactory.

This is great news! It's not working for me quite yet, but I'm refreshing my browser every 5 minutes. Next stop: Proper inline math.

The big advantage of using code blocks is that is guarantees that their sanitizer doesn't mess with the contents. This is a pretty big plus.

Also, you can of course still have mermaid code blocks; just don't put `mermaid` after the three backticks. The code block won't have any syntax highlighting, but in the case of `math`, this wouldn't make sense anyway.

I agree: If you're choosing dollar signs for your math delimiters, you can't expect them to work as regular dollar signs anymore; just like backticks.

> sounds like the parsing operations are done in the wrong order.

Indeed!

> I've used jupyter-book to typeset math-in-markdown before now,

They're using $-math as well?

Probably pandoc protects whatever is inside $...$ or $$...$$. GitHub doesn't. I would be curious to know how pandoc handles the other failing cases.

There are many approaches to this problem. E.g., Jupyter notebooks implement one that has matured in the wild over a decade. There's this very flexible markdown-it plugin that implements anther https://github.com/goessner/markdown-it-texmath, and my version of it here https://github.com/sagemathinc/cocalc/blob/master/src/packag... which I rewrote in typescript with a focus on the same semantics as Jupyter has, but for CoCalc. I've also been working on using unifiedjs to provide more general latex for Markdown (not just formulas) here https://github.com/sagemathinc/cocalc/pull/5982

Parsing math in markdown is easier if you use a plugin to an existing markdown parser, rather than trying to do some hack outside of that (which is what Github probably does, and also what Jupyter does).

Well, it _is_ (La)TeX syntax. With the exception that there, if you want a dollar sign, you have to type \$. But yeah, the syntax isn't made for Markdown.

I think the problem is the change. You didn't need \$ before, and now people's files are broken.

GitHub could have run their parser on a sample of existing Markdown file and check that the output doesn't change. They have such a huge corpus, with author date info, it is so easy to test that files authored before the feature don't trigger the feature.

In May, GitHub added native math support. Unfortunately, it left lots to be desired. Six weeks later, I'm taking another look. Have the major issues been fixed? (Spoiler: No.)

I have been using gist for my Spivak calculus problems. Often I write down on a notebook and then transcribe it to the $<latex>$ format. Along with the other markdown features it has been enough.

Plain latex has a steep curve and not friendly for mobile typing. Plain text is hard to read and hinders the actual math understanding. Therefore, i use gist markdown.

Author here. Thanks for the comment!

The main problems pointed out in the blog post are problems in _parsing_ the Markdown+TeX pages. The output could be MathML indeed, but this is an issue they could always fix later.

Author here.

That is interesting! Have you tried it on the examples in the blog post? I'd be curious to see.