markup: reStructuredText does not support math

</sigh>

It’s been nine years, guys. Math is kinda important. It’d be nice if GitHub supported math rendering – any math rendering. It doesn’t particularly matter how this gets done, only that this does eventually get done. LaTeX is preferable, but MathJax is fine. Anything is fine, because the current ad-hoc situation is obscure CDN-hosted JavaScript hacks, which is probably worse than nothing and exposes everyone involved (including GitHub itself) to undue security, privacy, and performance concerns.

Note that GitHub already supports LaTeX math rendering in Jupyter notebooks. Amusingly, hijacking this support to render LaTeX math in README.md and README.rst files via GitHub-hosted URLs generated by external webapps (or just manually URL-encoding the LaTeX yourself) is then trivial. These include:

• tex image link generator.
• jsfiddle.
• Math to Image.

So GitHub already self-hosts arbitrary LaTeX math as globally accessible images (despite the supposed security and performance concerns) – but fails to integrate that support with most of its external rendering pipeline, leaving third-party converters to pick up the pieces. Some things make no sense. This is one of them.

And please don’t lock this issue like you have every other popular issue on this topic (e.g., #274, #897). Locking issues is a great way to ensure nothing gets done… unless nothing getting done is the intended effect.

Please upvote this feature request. It seems like it got into the internal feature request list. It might gain more traction if more people upvote it.

Do we have any links to what other rst rendering engines are doing? Sounds like the math code block is most common today in rst’s?

Do folks need the inline variant?

Is a client side rendering going to work?

Would love to know more about what the common practices are amongst rst folks and see if I can advocate for support. I haven’t dug into the HTML pipeline at all for rst files yet so don’t know how big an ask this is. But it’s gotta be easier now surely? (Famous last words in my line of work)

Can mathml.css (via MDN) be a possible solution?

Its test page looks fine in most browsers. Probably only IE9/8 would be an issue since they still have quite significant shares.

I personally use MathML output for math_output in reST, if GitHub allows MathML, then this would not only benefit reST users, but also the markups that allow the use/passthrough of MathML.

So far, only Firefox and Safari support native MathML, but with this CSS, it wouldn’t matter.

#274 was closed due to the issue not in markup (and the thread is locked, can’t comment there), but if GitHub decides to use this, the the math_output needs to be changed.

Even GitHub does not, would you consider to use HTML math.css output, with docutils’ math.css? In Firefox, it doesn’t look as good as MathML, but it’s better than nothing.

👍 I don’t know about the other markups, but the .. math:: and :math: directives are very common in reStructuredText. This would be a win, IMO…

Awesome thanks. I’ll go take a look

@martinwoodward I know that markdown/rst now supports math mode using $ and $$ (issue #274). Would it be possible to reopen this to also support the math block in rst? This would be very useful for documenting scientific Python packages.

In particular, I would appreciate it for mwt/inteq. I use a readme.rst file that is imported as the introduction of my online documentation. To make it work in both, I currently use images of the equations. These images break in dark mode.

I think this would just require a custom rst role that wraps with $ in inline mode and $$ in multiline mode.