How to show math equations in general github's markdown(not github's blog)
GithubMarkdownMathjaxGithub Problem Overview
After investigating, I've found mathjax can do this. But when I write some example in my markdown file, it doesn't show the correct equations:
I have added this in the head of markdown file:
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=default"></script>
And type the mathjax statement:
\(E=mc^2\),$$x_{1,2} = \frac{-b \pm \sqrt{b^2-4ac}}{2b}.$$
But github shows nothing for the math symbols! Please help me, thanks! Tell me how to show math symbols in github markdown pages.
Github Solutions
Solution 1 - Github
>But github show nothing for the math symbols! please help me, thanks!
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, considering your question :).
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.
>Tell me how to show math symbols in general github markdown.
Your best bet would be to find a website similar to yuml.me which can generate on-the-fly images from by parsing the provided URL querystring.
Update
I've found some sites providing users with such service: codedogs.com (no longer seems to support embedding) or iTex2Img. You may want to try them out. Of course, others may exist and some Google-fu will help you find them.
given the following markdown syntax
![equation](http://www.sciweavers.org/tex2img.php?eq=1%2Bsin%28mc%5E2%29&bc=White&fc=Black&im=jpg&fs=12&ff=arev&edit=)
it will display the following image
Note: In order for the image to be properly displayed, you'll have to ensure the querystring part of the url is percent encoded. You can easily find online tools to help you with that task, such as www.url-encode-decode.com
Solution 2 - Github
Markdown supports inline HTML. Inline HTML can be used for both quick and simple inline equations and, with and external tool, more complex rendering.
Quick and Simple Inline
For quick and simple inline items use HTML ampersand entity codes. An example that combines this idea with subscript text in markdown is: hθ(x) = θo x + θ1x, the code for which follows.
h<sub>θ</sub>(x) = θ<sub>o</sub> x + θ<sub>1</sub>x
HTML ampersand entity codes for common math symbols can be found here. Codes for Greek letters here. An extensive list html entity codes to Unicode characters can be found here.
While this approach has limitations it works in practically all markdown and does not require any external libraries.
Complex Scalable Inline Rendering with LaTeX and Codecogs
If your needs are greater use an external LaTeX renderer like CodeCogs. Create an equation with CodeCogs editor. Choose svg for rendering and HTML for the embed code. Svg renders well on resize. HTML allows LaTeX to be easily read when you are looking at the source. Copy the embed code from the bottom of the page and paste it into your markdown.
<img src="https://latex.codecogs.com/svg.latex?\Large&space;x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}" title="\Large x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}" />
https://latex.codecogs.com/svg.latex?\Large&space;x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}" title="\Large x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}" />
Expressed in markdown becomes
![\Large x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}](https://latex.codecogs.com/svg.latex?\Large&space;x=\frac{-b\pm\sqrt{b^2-4ac}}{2a})
This combines this answer and this answer.
GitHub support only somtimes worked using the above raw html syntax for readable LaTeX for me. If the above does not work for you another option is to instead choose URL Encoded rendering and use that output to manually create a link like:
![\Large x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}](https://latex.codecogs.com/svg.latex?x%3D%5Cfrac%7B-b%5Cpm%5Csqrt%7Bb%5E2-4ac%7D%7D%7B2a%7D)
This manually incorporates LaTex in the alt image text and uses an encoded URL for rendering on GitHub.
Multi-line Rendering
If you need multi-line rendering check out this answer.
Solution 3 - Github
It ’s 2020 now, let me summarize the progress of the mathematical formula rendering support of source code repository hosts.
GitHub & Bitbucket
GitHub and Bitbucket still do not support the rendering of mathematical formulas, whether it is the default delimiters or other.
> Bitbucket Cloud / BCLOUD-11192 -- Add LaTeX Support in MarkDown Documents (BB-12552) > > GitHub / markup -- Rendering math equations > > GitHub / markup -- Support latex > > GitHub Community Forum -- [FEATURE REQUEST] LaTeX Math in Markdown > > talk.commonmark.org -- Can math formula added to the markdown
GitHub has hardly made any substantial progress in recent years.
GitLab
GitLab is already supported, but not the most common way. It uses its own delimiter.
This math is inline $`a^2+b^2=c^2`$.
This is on a separate line
```math
a^2+b^2=c^2
```
> GitLab Flavored Markdown -- Math
Who supports the universal delimiters?
A Markdown parser used by Hugo
Other ways to render
-
Use web api to render according to A hack for showing LaTeX formulas in GitHub markdown, you can even write jupyter notebook.
Solution 4 - Github
Another possibility is to rely on GitHub's own notebook renderer. This even works right here in SO.
To render x_{1,2} = \frac{-b \pm \sqrt{b^2-4ac}}{2b}
use the following HTML img
tag:
<img src="https://render.githubusercontent.com/render/math?math=x_{1,2} = \frac{-b \pm \sqrt{b^2-4ac}}{2b}">
Live Demo:
https://render.githubusercontent.com/render/math?math=x_{1,2} = \frac{-b \pm \sqrt{b^2-4ac}}{2b}">
What's great about this approach is that you can edit your formula directly in Markdown and the preview will update accordingly.
You can try it out by editing this answer. (Just throw away your edits if they don't add to the answer ;))
Source: https://gist.github.com/a-rodin/fef3f543412d6e1ec5b6cf55bf197d7b
Solution 5 - Github
One other work-around is to use jupyter notebooks and use the markdown mode in cells to render equations.
Basic stuff seems to work perfectly, like centered equations
\begin{equation}
...
\end{equation}
or inline equations
$ \sum_{\forall i}{x_i^{2}} $
Although, one of the functions that I really wanted did not render at all in github was \mbox{}
, which was a bummer. But, all in all this has been the most successful way of rendering equations on github.
Solution 6 - Github
If just wanted to show math in the browser for yourself, you could try the Chrome extension GitHub with MathJax. It's quite convenient.
Solution 7 - Github
While GitHub won't interpret the MathJax formulas, you can automatically generate a new Markdown document with the formulae replaced by images.
I suggest you look at the GitHub app TeXify:
> GitHub App that looks in your pushes for files with extension *.tex.md and renders it's TeX expressions as SVG images
How it works (from the source repository):
>Whenever you push TeXify will run and seach for *.tex.md files in your last commit. For each one of those it'll run readme2tex which will take LaTeX expressions enclosed between dollar signs, convert it to plain SVG images, and then save the output into a .md extension file (That means that a file named README.tex.md will be processed and the output will be saved as README.md). After that, the output file and the new SVG images are then commited and pushed back to your repo.
Solution 8 - Github
I use the below mentioned process to convert equations to markdown. This works very well for me. Its very simple!!
Let's say, I want to represent matrix multiplication equation
Step 1:
Get the script for your formulae from here - https://csrgxtu.github.io/2015/03/20/Writing-Mathematic-Fomulars-in-Markdown/
My example: I wanted to represent Z(i,j)=X(i,k) * Y(k, j); k=1 to n
into a summation formulae.
Referencing the website, the script needed was => Z_i_j=\sum_{k=1}^{10} X_i_k * Y_k_j
Step 2:
Use URL encoder - https://www.urlencoder.org/ to convert the script to a valid url
My example:
Step 3:
Use this website to generate the image by copy-pasting the output from Step 2 in the "eq" request parameter - http://www.sciweavers.org/tex2img.php?eq=<b><i>paste-output-here</i></b>&bc=White&fc=Black&im=jpg&fs=12&ff=arev&edit=
- My example:
http://www.sciweavers.org/tex2img.php?eq=Z_i_j=\sum_{k=1}^{10}%20X_i_k%20*%20Y_k_j&bc=White&fc=Black&im=jpg&fs=12&ff=arev&edit=
Step 4:
Reference image using markdown syntax - ![alt text](enter url here)
- Copy this in your markdown and you are good to go:
![Z(i,j)=X(i,k) * Y(k, j); k=1 to n](http://www.sciweavers.org/tex2img.php?eq=Z_i_j%3D%5Csum_%7Bi%3D1%7D%5E%7B10%7D%20X_i_k%20%2A%20Y_k_j&bc=White&fc=Black&im=jpg&fs=12&ff=arev&edit=)
Image below is the output of markdown. Hurray!!
Solution 9 - Github
I just released a little Chrome extension, xhub, that lets you use LaTeX math (and more) in GitHub pages.
Pros:
- You don't have to set up anything in your repo, just use math in your Markdown (sytax from GitLab):
Some display math: ```math e^{i\pi} + 1 = 0 ``` and some inline math, $`a^2 + b^2 = c^2`$.
- It works on light and dark backgrounds alike.
- You can copy-and-paste the math
Cons:
- You have to install a browser extension once.
Solution 10 - Github
There is good solution for your problem - use TeXify github plugin (mentioned by Tom Hale answer - but I developed his answer in given link below) - more details about this github plugin and explanation why this is good approach you can find in that answer.
Solution 11 - Github
I used the following in the head of mark down file
<script type="text/javascript" async
src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?
config=TeX-MML-AM_CHTML"
</script>
Then typed the following mathjax statement
$$x_{1,2} = \frac{-b \pm \sqrt{b^2-4ac}}{2b}.$$
It worked for me
Solution 12 - Github
A "quick and dirty" solution is to maintain a standard .md file using standard TeX equations, e.g. _README.md
.
When you are satisfied, pass the entire file through Pandoc to convert from standard Markdown
to Markdown (Github flavour)
, and copy the output to README.md
.
You can do this online for a quick turnaround, or install/configure Pandoc locally.
Solution 13 - Github
Mathcha is a sophisticated mathematics editor, but it can be used to render individual equations and save them as pure html, which you can then add to your documents as inline html OR you can save as SVG and insert as an image. https://www.mathcha.io/
Solution 14 - Github
You can embed your LaTeX in an image URL rendered by render.githubusercontent.com
such as this one:
<img src="https://render.githubusercontent.com/render/math?math={x + y}">
which will render like this:
https://render.githubusercontent.com/render/math?math={x + y}">
Which you'll notice is missing the +
sign. To fix that you can URL encode the plus sigh as %2b
or URL encode the entire equation, which will render like so:
https://render.githubusercontent.com/render/math?math={x%20%2b%20y}">
Unfortunately this will always render in black, so you'll want to use this GitHub specific trick to render white text for users using dark mode and black text to users using light mode, by including the equation once with the #gh-light-mode-only
and again with the LaTeX comand \color{white}
and the #gh-dark-mode-only
tag:
<img src="https://render.githubusercontent.com/render/math?math={x - y}#gh-light-mode-only">
<img src="https://render.githubusercontent.com/render/math?math={\color{white}x - y}#gh-dark-mode-only">
which will display this to light mode users:
https://render.githubusercontent.com/render/math?math={x-y}#gh-light-mode-only">
and display this to dark mode users:
https://render.githubusercontent.com/render/math?math={\color{white}x-y}#gh-dark-mode-only">
Solution 15 - Github
Regarding tex→image conversion, the tool LaTeXiT produces much higher quality output. I believe it is standard in most TeX distributions but you can certainly find it online if you don't already have it. All you need to do is put it in the TeX, drag the image to your desktop, then drag from your desktop to an image hosting site (I use imgur).
Solution 16 - Github
TeXify is no longer working. Check my repo readme2tex-action on how to create Github actions.
- Add action.yml file to your repo at
.github/workflows/action.yml
. - Change branch
main
name if it is necessary.