github / markup

Determines which markup library to use to render a content file (e.g. README) on GitHub
MIT License
5.86k stars 3.39k forks source link

Math support does not work reliably #1709

Closed v0lta closed 1 year ago

v0lta commented 1 year ago

Consider, for example, the formula below:


Reuse your MNIST digit recognition code. Implement IG, as discussed in the lecture. Recall the equation

$$ \text{IntegratedGrads}_i(x) = (x_i - x_i') \cdot \sum_{k=1}^m \frac{\partial F (x' + \frac{k}{m} \cdot (x - x'))}{\partial x_i}. $$

Vscode's preview feature will render the formula correctly. However, the same .md file won't be displayed correctly on github.com.

A larger example is available at:

https://github.com/Deep-Learning-with-Jax/day_04_exercise_statistics/blob/main/README.md

As you can see when scrolling down. Github.com gets the math wrong. https://github.com/Deep-Learning-with-Jax/day_04_exercise_statistics/blob/main/README.pdf was generated by pandoc which sets the formulae correctly.

Consequently, I think this is a GitHub problem, I am opening an issue here.

v0lta commented 1 year ago

It seems the indices are a problem in the current version,

$$\tilde{{x}}{ijk} = \frac{x{ijk} - \mu}{\sigma}$$

worked in March. Now a simplification to

$$\tilde{{x}} = \frac{x - \mu}{\sigma}$$

is required to make it work. This is very unfortunate because I happen to maintain a course with a Github classroom that relies on this feature. Without it, the math in all task readmes looks broken.

v0lta commented 1 year ago

I think I understand this now. Github needs an escape slash now to understand the underscore:

$$\tilde{{x}}_{ijk} = \frac{x_{ijk} - \mu}{\sigma}$$

That is use \_ instead of _ in math formulae for correct results.

v0lta commented 1 year ago

Unfortunately vscodes preview feature does not understand the escape slash. Having to choose either a correct display on github.com or within vscode is painful.

v0lta commented 1 year ago

Github and vscode use different markdown specifications, so this behaviour is expected. The two won't work together: Does VS Code support GitHub Flavored Markdown?

No, VS Code targets the CommonMark Markdown specification using the markdown-it library. GitHub is moving toward the CommonMark specification, which you can read about in this update.