GitHub's "Math Processing Error" when rendering Jupyter notebooks

[rsvp]

Description of specific issue

Mathematical equations, in both inline and display modes, render correctly when viewed in local browser -- however, when a Jupyter notebook with such equations is viewed at GitHub the following message is generated: "Math Processing Error"

The issue can be traced solely to GitHub since a notebook's source commited to a GH repo viewed through http://nbviewer.jupyter.org renders the math correctly.

• [x] Bug at Github itself, not here at fecon235

  Expected behavior

Here's the correct renderings via http://nbviewer.jupyter.org/github/rsvp/fecon235/blob/master/nb/qdl-spx-earn-div.ipynb while noticing the actual source code resides at GitHub.

Observed behavior

Here's the problematic rendering at GitHub: https://github.com/rsvp/fecon235/blob/master/nb/qdl-spx-earn-div.ipynb where all the math is replaced by this message, "Math Processing Error".

Steps towards resolution

1. Contact GitHub admin directly. Their notebook rendering library is apparently proprietary -- supposedly for security reasons.

   Additional helpful details for bugs

   • [x] Problem started recently, but not in older versions: YES.
   • [x] Problem happens with all files, not only some files: notebooks with math.
   • [x] Problem can be reliably reproduced: YES, locally and above proof.
   • [ ] Problem happens randomly: NO.
   • fecon235 version: v4.16.0329

ATTN mention: @rsvp

[rsvp]

My understanding from chats is that GitHub could be timing out on rendering LaTeX equations embedded within markdown cells -- and that "Math Processing Error" is about their choking, rather than LaTeX format errors.

[rsvp]

Interestingly, @jdfreder said:

Jan 07 10:20 @rsvp GitHub does not support math rendering IIRC Also, I think their renderer is closed source

https://gitter.im/jupyter/jupyterhub/archives/2016/01/07

Then I remember the difficulty in tracking down the GitHub developer for their (closed?) rendering engine. Why not just adopt the code from http://nbviewer.jupyter.org ?

[rsvp]

@willingc, a Jupyter member, kindly commented in https://github.com/jupyter/help/issues/21 :

Since this looks to be an upstream issue with GitHub since I don't believe that they currently support LaTeX rendering in their service, I'm labeling it as such.

[rsvp]

Interim discussion at Jupyter: https://github.com/jupyter/help/issues/21 where the primary developers are mentioned for further follow-up. @jasongrout commented: "[T]his is a problem on Github's end, or at least it needs to be worked on by Github, since we don't see what they are doing to render the page."

Observed behavior, updated 2016-11-15

Errors still persist in regards to rendering at GitHub, esp. annoying when superscripts and subscripts are involved. For some reason, the font size is half of what is expected.

For some lurid examples, see https://github.com/jupyter/nbviewer/issues/452 where some difficulties can be traced to version and type of browser used.

Recommend rendering LaTeX on your local machine for best results, otherwise the mathematical equations could wrongly appear incoherent.

[rsvp]

Security issues

GitHub member @bkeepers commented on Apr 2, 2014: "Yep. latex just has so many feature that it's impossible for us to deploy it securely right now." https://github.com/github/markup/issues/274 But specifics on security were not discussed.

One year later, we understand that: "GitHub markdown parsing is performed by the SunDown (ex libUpSkirt) library. The motto of the library is "Standards compliant, fast, secure markdown processing library in C". The important word being "secure" there. Indeed, allowing javascript to be executed would be a bit off of the MarkDown standard text-to-HTML contract. Moreover, everything that looks like a HTML tag is either escaped or stripped out." See http://stackoverflow.com/questions/11256433/how-to-show-math-equations-in-general-githubs-markdownnot-githubs-blog

[rsvp]

Styles for equations

As of 2017-06-03, the appearance of "Math Processing Error" at GitHub has diminished considerably. However, the font size, is rendered inconsistently -- often too small. They may remedy this upstream, but in the meantime, consider using LaTeX styles: \displaystyle \textstyle \scriptstyle \scriptscriptstyle ordered from largest to smallest.