Improved math rendering in github documents

[bakaburg1]

Hello,

I recently stumble upon this solution for having math formulas in github readme documents which provide much better quality images than the current system: https://gist.github.com/a-rodin/fef3f543412d6e1ec5b6cf55bf197d7b

Could it be a good improvement?

[atusy]

Interesting. Your reference shows inline math, and I tested display math is also available.
I think this feature can be implemented by a lua filter, but might be a bit complicated because we need URL encoding.

![](https://render.githubusercontent.com/render/math?math=e%5E%7Bi%20%5Cpi%7D%20%3D%20-1&mode=display)

[bakaburg1]

At the moment I was thinking about doing a script in R which convert the actual include code by markdown. but surely something native would be better.

[atusy]

A script in R is possible, but I'm sure developers go into regex-hell.

[atusy]

Here's a lua filter.

https://github.com/atusy/lua-filters/blob/master/lua/math-github.lua

I wanna make some improvements so to

• Call R by path instead of a command
• Add alt to image for accessibility

After that, maybe we can add the lua filter to github_document and potentially to other formats.

[bakaburg1]

ehm, sorry the silliness but, how does one use it? 😆

[atusy]

@bakaburg1

Download the file and render something like

---
output:
  github_document:
    pandoc_args: ['--lua-filter', 'math-github.lua']
---

$\alpha$

[atusy]

I noticed that webtex will be a better solution from https://pandoc.org/MANUAL.html#option--webtex .
GitHub's math rendering engine is not documented, and does not really support display math (it just becomes inline math).

[bakaburg1]

ok, thanks!

[cderv]

It seems with latest Pandoc, math are transformed into markdown directly.

---
title: "Basic Stats"
output: github_document
---

$e^{i \pi} = -1$

will output

Basic Stats
================

*e*<sup>*i**π*</sup> =  − 1

Which renders as

---

Basic Stats

e^i**π =  − 1

---

It seems the change in Pandoc 2.10.1 with gfm and commonmark could be the reason. Or another but I don't see what in the release note and not specific mention of this transformation in the release note.

it is note quite perfect because there is 2 * not correctly process, but it is quite an evolution.

This can be seen easily if you are using RStudio 1.4 preview, as it is shipped with recent Pandoc and you should see the difference.

This happens with several formats

$ pandoc -t gfm <<< '$e^{i \pi} = -1$'
*e*<sup>*i**π*</sup> =  − 1
$ pandoc -t commonmark <<< '$e^{i \pi} = -1$'
*e*<sup>*i**π*</sup> =  − 1
$ pandoc -t commonmark_x <<< '$e^{i \pi} = -1$'
$e^{i \pi} = -1$
$ pandoc -t markdown_strict <<< '$e^{i \pi} = -1$'
*e*<sup>*i**π*</sup> =  − 1

[cderv]

It seems the change in Pandoc 2.10.1 with gfm and commonmark could be the reason. Or another but I don't see what in the release note and not specific mention of this transformation in the release note.

It seems gfm now default to the default behavior of Pandoc which try to render using unicode when possible.
See: https://pandoc.org/MANUAL.html#math-rendering-in-html

The default is to render TeX math as far as possible using Unicode characters

There is discussion about this here: https://groups.google.com/g/pandoc-discuss/c/gYIXVJ944S0/m/wYZgs6cnBQAJ

It won't work with complex equation where it is not converted and leave as is

---
title: "Basic Stats"
output: github_document
---

$$
Sensitivity \equiv TPR = \frac{TP}{OP} = P(T+ | D+)  = 0.938
$$

I think adding --webtex command flag for md_document output could be a good way to support math, but only inline math. (Thanks @ausy for noticing this!)

Example:

---
title: "Basic Stats"
output: 
  github_document:
    pandoc_args: "--webtex"
---

Inline math: $e^{i \pi} = -1$

Display math: 

$$
\frac{e^{i \pi}}{10}
$$

[atusy]

@cderv

Thanks for the news on latest pandoc.

--webtex command flag for md_document output could be a good way to support math, but only inline math.

What do you mean by only inline math?
As far as I tried with latest rmarkdown and pandoc 2.7.3, it is correctly rendered, though it is aligned left.

BTW, I have opened PR #1940 to support variety of math rendering engines on HTML formats.
I would love to generalize it to other formats afterwards.

[cderv]

What do you mean by only inline math?
As far as I tried with latest rmarkdown and pandoc 2.7.3, it is correctly rendered, though it is aligned left.

When I try the above using latest Pandoc (2.11.3.2) it does not work with the display equation. Seems like a regression with Pandoc.

I saw your PR. I need to take some time looking through it and through the different options for this. We'll discuss there.

[cderv]

Sharing here that a new package by rOpenSci in on CRAN now : https://docs.ropensci.org/katex/reference/katex.html.

It enables server-side math-to-html rendering in R, such that no javascript library is needed in the html document. It would maybe help with this specific issue of github document

[ThierryO]

I'm face with the some problem. I end up write these functions below. I use it for my blog based on Hugo. Adding <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script> to the HTML pages gives the MathJax look to the equations.

library(katex)
math_display <- function(tex) {
  x <- vapply(tex, katex_mathml, character(1), displayMode = TRUE)
  x <- gsub("<annotation(.*?)\\/annotation>", "", x)
  cat(x)
}

math_inline <- function(tex) {
  x <- katex_mathml(tex = tex, displayMode = FALSE)
  x <- gsub("<annotation(.*?)\\/annotation>", "", x)
  cat(x)
}

The gsub() is required to remove some unwanted artefacts from some equations.

[github-actions]

This old thread has been automatically locked. If you think you have found something related to this, please open a new issue by following the issue guide (https://yihui.org/issue/), and link to this old issue if necessary.