reStructuredText does not support math

[fonnesbeck]

I have tried every approach for embedding equations into my rst markup on Github, but none seem to work:

.. math::

    \beta = \alpha + \epsilon^2

and

.. raw:: latex html

    \[  \beta = \alpha + \epsilon^2 \]

as well as adding a MathJax script to the rst file.

Since I largely develop statistical software, its important to be able to add math to my wiki pages and docs. Is this something that will be added in the near future, or is there a workaround?

[WillForan]

Do any of the other markup languages have github support for math markup?

[jakebiesinger]

👍 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..

[navilan]

+1.

[js850]

+1

[bkeepers]

We have experimented with math support for various markup formats in the past, but haven't found any that are easy to maintain (MathJax) or free of security issues (latex).

[bkeepers]

Closing in favor of #274.

[livibetter]

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.

[damaon]

Any updates on this?

[mrandrewandrade]

+1 + 10 from here: #274

[michaelmyc]

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.

[leycec]

</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.

[mwt]

@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.

[martinwoodward]

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)

[mwt]

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?

The math role/directive are part of the official rst spec (documented here).

The package that you use for rst (docutils) supports mathjax natively. However, markup currently bypasses this support. I think that changing this line

markup/lib/github/commands/rest2html

Line 161 in b2230a2

'math_output': 'latex',

to 'math_output': 'mathjax', (as documented here) should get you a good part of the way there. This would use \( x \) and \[ x \] instead of $ x $ and $$ x $$ respectively for mathjax. Switching those to dollar signs might be kind of complex because you don't want to interpret anything in a code block.

It might be easier for you to use the default directional brackets in mathjax whenever the file is rst?

[martinwoodward]

Awesome thanks. I'll go take a look

[aki-nishimura]

+1

[alexshirley]

+1

[echedey-ls]

+1

[marshallward]

Another +1 to please add support for math rendering in restructuredtext. It ought to be a simple task since the reST tools do the hard part.

Please look at this repository, just to illustrate that Markdown is working but reST is not. It also includes sample output generated by rst2html and pandoc, with Makefile attached. I am willing to iterate further on this to help find a solution which matches GitHub's requirements.

https://github.com/marshallward/rest_math_render

IMO this issue should be reopened. Even if Markdown supports math, reST still does not.