Issue #5420 resolved

Enable MathJax for ReStructuredText files. (BB-6684)

Michael Forbes
created an issue

Could the --math-output option please be enabled for the ReStructuredText interpreter so that MathJax output is supported in the README.rst and similar ReST files. This would be extremely useful for documenting project code on the project overview page.


Comments (28)

  1. Michael Forbes reporter

    Sorry for the noise, but this should be a simple fix since docutils already supports MathJax. Please let us know if this is going to happen or if we need to take math-related projects to github.

    Thanks, Michael.

  2. Michael Forbes reporter

    Is there anything I can do to help get this working quickly? It would be extremely useful, and as an hg user, there is non-trivial inertia for a github migration.

    Thanks, Michael.

  3. optimizer

    Github doesn't allow you to display math using mathjax in a project's README if it's in Markdown (because they use the Sundown library I believe). Do they really allow it in Restructured Text??? I was browsing here because I'm frustrated that Github won't let me display math. Not even in the project pages if they're auto-generated.

  4. Michael Forbes reporter

    Hmm. I could have sworn that this was enabled at some point, but it looks now like github it not an option either. I really hope someone at bitbucket picks this up as it would be extremely useful for some users.

  5. Michael Forbes reporter

    Michael Frauenholtz Ping: Any possibility that MathJax this could be enabled for the overview pages? It really should be as simple as changing a configuration flag for docutils. It would be extremely useful for physics and math-related projects.

  6. Matt Knepley

    Yes, this would be the opportunity to beat the crap out of GitHub. These issues have been open on both sites for a long time, and there has been considerable wailing and gnashing of teeth on the science groups. Is this really that hard?

  7. Michael Forbes reporter

    Thanks: That is great!

    The only issue I see so far is that the style somehow causes numbers and a few symbols (like sqrt signs, =, etc.) to be black, while some parts are coloured. I traced the coloring to the following style: .mo { color: #099 } /* Literal.Number.Oct */ in one of the stylesheets... not exactly sure why this is being applied to things like equal signs. (See for example

    Should I open a new issue for this?

  8. VladimirSZ

    MathJax in *.rst not rendered. First noticed it a week ago. I'm able to reproduce this behavior on Win7 with Chrome, Firefox, IE (10,11), Opera and on Ubuntu 14.04 with Firefox (v 30.0)

  9. Michael Forbes reporter
    • changed status to open

    As others point out, it appears as if this feature is now broken as of a few weeks ago, even in project-level README.rst files where it used to work.

  10. Michael Frauenholtz staff

    Hi dmahler

    Sorry about that. From what I can see, it looks like we are rendering README.rst files as plain text on the repository overview page. Also, when navigating to an .rst file in the source browser, MathJax only renders properly for a README in the directory view, but not the actual file. I'll try to get that fixed up soon. Is there anywhere else that isn't working for you?

  11. Michael Frauenholtz staff

    This is fixed again now for the source view.

    For the repository overview, we are going to reduce how strictly we parse reStructuredText READMEs. You will be less likely to have a rendering error that causes us to show your README as plain text. We will roll this out some time next week.


  12. Log in to comment