Repository navigation
reStructuredText does not support math #83
Description
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?
Activity
WillForan commentedon Apr 24, 2012
Do any of the other markup languages have github support for math markup?
jakebiesinger commentedon Jul 9, 2013
👍 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 commentedon Sep 18, 2013
+1.
js850 commentedon Jan 7, 2014
+1
bkeepers commentedon Jan 28, 2014
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 commentedon May 29, 2014
Closing in favor of #274.
livibetter commentedon May 17, 2015
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
MathMLoutput formath_outputin 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_outputneeds to be changed.Even GitHub does not, would you consider to use
HTML math.cssoutput, with docutils' math.css? In Firefox, it doesn't look as good as MathML, but it's better than nothing.damaon commentedon Jun 8, 2015
Any updates on this?
mrandrewandrade commentedon Sep 25, 2015
+1 + 10 from here: #274
michaelmyc commentedon May 20, 2020
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 commentedon Sep 2, 2020
</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.mdandREADME.rstfiles via GitHub-hosted URLs generated by external webapps (or just manually URL-encoding the LaTeX yourself) is then trivial. These include: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 commentedon Jun 1, 2022
@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 commentedon Jun 2, 2022
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)
41 remaining items
mwt commentedon Mar 11, 2026
Not stale
github-actions commentedon May 11, 2026
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
mwt commentedon May 11, 2026
Not stale
github-actions commentedon Jul 12, 2026
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
marshallward commentedon Jul 12, 2026
Still broken: https://github.com/marshallward/rest_math_render/blob/main/README.rst
github-actions commentedon Sep 12, 2026
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
schlatterbeck commentedon Sep 13, 2026
Not obsolete