Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?

Problem

A lot of GitHub projects need to have pretty math formulas in READMEs, wikis or other markdown pages. The desired approach would be to just write inline LaTeX-style formulas like this:

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

Unfortunately, GitHub does not support inline formulas. The issue is tracked here.

Investigation

However, it does support them in Jupyter notebooks, scroll below to see an example. One might question how does it work in notebooks. It turns out that instead of relying on MathJax as nbviewer does, GitHub's notebooks renderer converts inline math to images with source URLs that look like this:

https://render.githubusercontent.com/render/math?math=e%5E%7Bi%20%5Cpi%7D%20%3D%20-1&mode=inline

Inspecting the URL, it is possible to notice that:

  1. The &mode=inline part is not required, the URL still returns the same image without it:

    https://render.githubusercontent.com/render/math?math=e%5E%7Bi%20%5Cpi%7D%20%3D%20-1.

  2. Modern browsers encode URLs automatically, thus this link would work as well:

    https://render.githubusercontent.com/render/math?math=e^{i \pi} = -1.

Solution

So the solution would be to insert this code in Markdown files:

<img src="https://render.githubusercontent.com/render/math?math=e^{i \pi} = -1">

and such an image would be rendered as .

This is more clumsy than just $e^{i \pi} = -1$, but it is still possible to write the formula by hand directly to the Markdown file this way.

Note that this syntax for image insertion would not work because the URL contains spaces:

![formula](https://render.githubusercontent.com/render/math?math=e^{i \pi} = -1)

Addition from 2019-10-30

I made a small app that allows to generate Markdown code from LaTeX using the method described above automatically.

Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@tpenguinltg

This comment has been minimized.

Copy link

tpenguinltg commented May 10, 2019

The Markdown image syntax should work if you replace the spaces with %20. Testing below:

formula

@daos20x15

This comment has been minimized.

Copy link

daos20x15 commented Aug 27, 2019

I wanted to write a formula with a "+" sign, but its apparently not working, any thoughts on how to make the "+" show?

<img src="https://render.githubusercontent.com/render/math?math=e^{i +\pi} =x+1">

This is the output:

@a-rodin

This comment has been minimized.

Copy link
Owner Author

a-rodin commented Aug 27, 2019

@daos20x15 + symbol is used to escape spaces in URI encoding and the formula has to be either properly escaped or at least don't conflict with possible escaped version created by the browser. The browser replaces spaces by + or %20 before sending to the server, so when it encounters + it assumes that it is already escaped and sends + sign as is, which is decoded by the server as a space. So + should be replaced by encoded version, which is %2B.

To be short: a formula with pluses should be written like this

<img src="https://render.githubusercontent.com/render/math?math=e^{i %2B\pi} =x%2B1">

which would be displayed as .

To encode other symbols or entire formulas you can use encodeURIComponent function from you browser's developer console.

@daos20x15

This comment has been minimized.

Copy link

daos20x15 commented Aug 27, 2019

@daos20x15 + symbol is used to escape spaces in URI encoding and the formula has to be either properly escaped or at least don't conflict with possible escaped version created by the browser. The browser replaces spaces by + or %20 before sending to the server, so when it encounters + it assumes that it is already escaped and sends + sign as is, which is decoded by the server as a space. So + should be replaced by encoded version, which is %2B.

To be short: a formula with pluses should be written like this

<img src="https://render.githubusercontent.com/render/math?math=e^{i %2B\pi} =x%2B1">

which would be displayed as ![](https://render.githubusercontent.com/render/math?math=e^{i %2B\pi} =x%2B1).

To encode other symbols or entire formulas you can use encodeURIComponent function from you browser's developer console.

This is very useful. Thanks a lot @a-rodin

@pedrolemoz

This comment has been minimized.

Copy link

pedrolemoz commented Oct 29, 2019

How to use this method to render brackets and sets (from mathematic)?

I tryed these:

![formula](https://render.githubusercontent.com/render/math?math=A%20-%20B%20=%20\{x%20\in%20\U%20\mid%20x%20\in%20A%20\land%20x%20\notin%20B%20\})

![formula](https://render.githubusercontent.com/render/math?math=A,%20B%20\in%20\U,%20x%20\in%20\Z)

And I get:

formula

formula

But, if I try to add a bracket...

![formula](https://render.githubusercontent.com/render/math?math=\left%20\{%20\right%20\})

formula

And if I try to add a set notation...

![formula](https://render.githubusercontent.com/render/math?math=\N\Z\R\Q\C)

formula

These aren't sets!

How can I get what I want?

@a-rodin

This comment has been minimized.

Copy link
Owner Author

a-rodin commented Oct 30, 2019

@pedrolemoz Braces ({}) need to be escaped by \ in LaTeX, square brackets ([]) can be used as is in LaTeX, but they collide with Markdown syntax and thus need to be URI-encoded.

I made a small app that converts LaTeX to Markdown code automatically. Here is an example that uses both braces, square brackets, and sets.

@jaimet

This comment has been minimized.

Copy link

jaimet commented Nov 21, 2019

Hi. Would you consider making a repo out of this? (I would like to add some content such as corrections and additional documentation, but I don't want to do it via comments on a gist.) Thank you for the original "hack" - it's brilliant!

@cjuicey

This comment has been minimized.

Copy link

cjuicey commented Dec 11, 2019

Worked. Thanks for the upload!

@chewxy

This comment has been minimized.

Copy link

chewxy commented Jan 17, 2020

This is brilliant. Thanks

@Mekahou

This comment has been minimized.

Copy link

Mekahou commented Feb 17, 2020

This is awesome. Thanks a lot!

@behrouz-bakhtiari

This comment has been minimized.

Copy link

behrouz-bakhtiari commented Feb 24, 2020

Thank you very much. This is very useful. I am a little disappointed at Github, but this method is a life saver.

@joyjeni

This comment has been minimized.

Copy link

joyjeni commented Mar 20, 2020

%2B

Thankyou It worked

@kartynnik

This comment has been minimized.

Copy link

kartynnik commented Apr 4, 2020

@a-rodin Why are you using KaTeX for previews in your app? It seems natural to give the "WYSIWYG" feedback by showing the exact image as rendered by the GitHub's renderer.

@manueltonneau

This comment has been minimized.

Copy link

manueltonneau commented Apr 5, 2020

Thank you very much, very cool stuff! If anybody was wondering how to render the equation in a bigger size, just write height="50" width="500" (just adapt the values to your case) after the last " and before >.

@a-rodin

This comment has been minimized.

Copy link
Owner Author

a-rodin commented Apr 5, 2020

@kartynnik The preview images are returned by GitHub, so they look exactly the same as they would on GitHub.

However, in case of parsing errors GitHub doesn't provide an error message, but just returns HTTP 406 error code. In such cases the formulas are additionally parsed using KaTeX and if KaTeX parser detects any error, such an error is displayed to the user to make it easier to fix it. That's why the previews are not instant, but take some time to show up.

@a-rodin

This comment has been minimized.

Copy link
Owner Author

a-rodin commented Apr 5, 2020

@mananeau It is also possible to add one of the following modifiers at the beginning of the formula to change the font size:

Modifier Example Rendered
none e^{i\pi} = -1 e^{i\pi} = -1
\large \large e^{i\pi} = -1 \large e^{i\pi} = -1
\Large \Large e^{i\pi} = -1 \Large e^{i\pi} = -1
\LARGE \LARGE e^{i\pi} = -1 \LARGE e^{i\pi} = -1
\huge \huge e^{i\pi} = -1 \huge e^{i\pi} = -1
\Huge \Huge e^{i\pi} = -1 \Huge e^{i\pi} = -1
@kartynnik

This comment has been minimized.

Copy link

kartynnik commented Apr 5, 2020

@a-rodin Makes perfect sense, thanks!

@gopal151295

This comment has been minimized.

Copy link

gopal151295 commented May 2, 2020

@a-rodin This is really great

@lucasabdalah

This comment has been minimized.

Copy link

lucasabdalah commented May 5, 2020

It's a really good tool.

Even if it seems better than the last tool that I used, it has a problem to handle with multiple lines (or matrices). When i tried to use 2 sequentially matrices instead it doesn't recognize as a matrix and leave it all on the same line.

\begin{pmatrix} 1 & 2 & 3\ a & b & c \end{pmatrix} = \begin{pmatrix} 1 & 2 & 3 \ a & b & c \end{pmatrix} = \begin{pmatrix} 1 & 2 & 3\ a & b & c \end{pmatrix}

image

I used to use this tool, however its preview is broke now.

@ninjakx

This comment has been minimized.

Copy link

ninjakx commented May 11, 2020

It's not working for me in .rst file
Works here:

There It's excluding the circular bracket.

@vrn25

This comment has been minimized.

Copy link

vrn25 commented May 23, 2020

@a-rodin is there any way for using $$e^{i \pi} = -1$$?

@psambit9791

This comment has been minimized.

Copy link

psambit9791 commented Jun 1, 2020

Much appreciation for sharing this. Saved me a good bit of time.

@ghost

This comment has been minimized.

Copy link

ghost commented Jun 13, 2020

This is wonderful. Thank you for posting this!!

@jk13o3lll

This comment has been minimized.

Copy link

jk13o3lll commented Jun 23, 2020

Here is a simple script to convert the equation into html: https://jsfiddle.net/8ndx694g/
For the following example, it works well.

\Huge
\begin{align*}
x&=1\\
x+y&=2\\
P&=\begin{bmatrix}p_1\\p_2\end{bmatrix}
\end{align*}
@cga203

This comment has been minimized.

Copy link

cga203 commented Jun 23, 2020

Hello @a-rodin, the link to your small app is broken.

@psireal9

This comment has been minimized.

Copy link

psireal9 commented Jun 24, 2020

The ![formula][url] doesnt work in an evironment ... (for example if you want to the your equation inside or "")

@iansyahr

This comment has been minimized.

Copy link

iansyahr commented Jun 30, 2020

omg it's working
@mubaraqwahab

This comment has been minimized.

Copy link

mubaraqwahab commented Jul 8, 2020

Thank you!

@Skywide1011

This comment has been minimized.

Copy link

Skywide1011 commented Jul 30, 2020

Here is a simple script to convert the equation into html: https://jsfiddle.net/8ndx694g/
For the following example, it works well.

\Huge
\begin{align*}
x&=1\\
x+y&=2\\
P&=\begin{bmatrix}p_1\\p_2\end{bmatrix}
\end{align*}

Thank you! It helped me a lot!

@spencerwooo

This comment has been minimized.

Copy link

spencerwooo commented Aug 2, 2020

Hi guys, me and my friends made a VS Code extension to convert math equations into rendered SVGs here: GitHub- vscode-math-to-image / VS Marketplace - Math to Image. We used the method mentioned in this gist to render external SVGs with GitHub math rendering servers. We also added a feature to render them into local SVGs with MathJax. Feel free to try it out!

@masakiaota

This comment has been minimized.

Copy link

masakiaota commented Aug 10, 2020

https://gist.github.com/a-rodin/fef3f543412d6e1ec5b6cf55bf197d7b#addition-from-2019-10-30

I made a small app that allows to generate Markdown code from LaTeX using the method described above automatically.

This link doesn't work... so I made new one
https://tex-image-link-generator.herokuapp.com/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.