235

Is there any way to render LaTex in README.md in a GitHub repository? I've googled it and searched on stack overflow but none of the related answers seems feasible.

8
  • 1
    It is not possible directly. Is there some specific thing that you think you need LaTex for? For example, if you want math equations, that may be doable with some specific tricks. Tell us what you want to render, and someone might be able to point you to a workaround.
    – Waylan
    Commented Feb 19, 2016 at 14:13
  • 2
    Yes I want math equations and aligned equations, along with inlined math symbols. That's pretty much it.
    – user90593
    Commented Feb 19, 2016 at 15:46
  • 1
    See this related post: How to show math equations in general github's markdown(not github's blog).
    – Waylan
    Commented Feb 19, 2016 at 16:07
  • 2
    have you considered using Jupyter notebooks? You can even insert python code now ;) Commented Jun 26, 2019 at 19:02
  • 6
    GitHub supports Latex/MathJax since May 2022.
    – VonC
    Commented May 19, 2022 at 19:46

17 Answers 17

78

For short expresions and not so fancy math you could use the inline HTML to get your latex rendered math on codecogs and then embed the resulting image. Here an example:

- <img src="https://latex.codecogs.com/gif.latex?O_t=\text { Onset event at time bin } t " /> 
- <img src="https://latex.codecogs.com/gif.latex?s=\text { sensor reading }  " /> 
- <img src="https://latex.codecogs.com/gif.latex?P(s | O_t )=\text { Probability of a sensor reading value when sleep onset is observed at a time bin } t " />

Which should result in something like the next

Update: This works great in eclipse but not in github unfortunately. The only work around is the next:

Take your latex equation and go to http://www.codecogs.com/latex/eqneditor.php, at the bottom of the area where your equation appears displayed there is a tiny dropdown menu, pick URL encoded and then paste that in your github markdown in the next way:

![equation](http://latex.codecogs.com/gif.latex?O_t%3D%5Ctext%20%7B%20Onset%20event%20at%20time%20bin%20%7D%20t)
![equation](http://latex.codecogs.com/gif.latex?s%3D%5Ctext%20%7B%20sensor%20reading%20%7D) 
![equation](http://latex.codecogs.com/gif.latex?P%28s%20%7C%20O_t%20%29%3D%5Ctext%20%7B%20Probability%20of%20a%20sensor%20reading%20value%20when%20sleep%20onset%20is%20observed%20at%20a%20time%20bin%20%7D%20t)
3
  • 9
    I suggest using latex.codecogs.com/png.latex instead of latex.codecogs.com/gif.latex; it returns better quality images!
    – Steffo
    Commented Apr 3, 2019 at 11:28
  • 19
    you could use latex.codecogs.com/svg.latex, it's resolution independent. Commented Apr 9, 2019 at 8:53
  • 1
    Works, but it doesn't work very well when user has a Dark or Dimmed Theme. Insert %5Cbg_white%20 after ? in the url to get a Black on White version.
    – Jan
    Commented Jun 7, 2021 at 15:34
64

I upload repositories with equations to Gitlab because it has native support for LaTeX in .md files:

```math
SE = \frac{\sigma}{\sqrt{n}}
```

The syntax for inline latex is $`\sqrt{2}`$.

Gitlab renders equations with JavaScript in the browser instead of showing images, which improves the quality of equations.

More info here.

Let's hope Github will implement this as well in the future.

3
  • @RylanSchaeffer <pre xml:lang="latex">\sqrt{2}</pre>, 🥰
    – LinconFive
    Commented Nov 28, 2020 at 2:04
  • 1
    @LinconFive thanks, but can you explain how to use it? I've just copy pasted this pre code into README.md on Github and it did not work (it just showed \sqrt{2} text)
    – Evgenii
    Commented Nov 29, 2020 at 3:16
  • @LinconFive I don't think it even works in plain HTML5. Commented Mar 2, 2022 at 20:07
38

My trick is to use the Jupyter Notebook.

GitHub has built-in support for rendering .ipynb files. You can write inline and display LaTeX code in the notebook and GitHub will render it for you.

Here's a sample notebook file: https://gist.github.com/cyhsutw/d5983d166fb70ff651f027b2aa56ee4e

0
30

Readme2Tex

I've been working on a script that automates most of the cruft out of getting LaTeX typeset nicely into Github-flavored markdown: https://github.com/leegao/readme2tex

There are a few challenges with rendering LaTeX for Github. First, Github-flavored markdown strips most tags and most attributes. This means no Javascript based libraries (like Mathjax) nor any CSS styling.

The natural solution then seems to be to embed images of precompiled equations. However, you'll soon realize that LaTeX does more than just turning dollar-sign enclosed formulas into images.

enter image description here

Simply embedding images from online compilers gives this really unnatural look to your document. In fact, I would argue that it's even more readable in your everyday x^2 mathematical slang than jumpy .

I believe that making sure that your documents are typeset in a natural and readable way is important. This is why I wrote a script that, beyond compiling formulas into images, also ensures that the resulting image is properly fitted and aligned to the rest of the text.

For example, here is an excerpt from a .md file regarding some enumerative properties of regular expressions typeset using readme2tex:

enter image description here

As you might expect, the set of equations at the top is specified by just starting the corresponding align* environment

**Theorem**: The translation $[\![e]\!]$ given by
\begin{align*}
...
\end{align*}
...

Notice that while inline equations ($...$) run with the text, display equations (those that are delimited by \begin{ENV}...\end{ENV} or $$...$$) are centered. This makes it easy for people who are already accustomed to LaTeX to keep being productive.

If this sounds like something that could help, make sure to check it out. https://github.com/leegao/readme2tex

3
  • 14
    Based on this work I've created a GitHub app that automates the rendering process, triggering it every time a push is made. I think it's useful so I share the link for those who wants to give it a try: github.com/agurz/github-texify Commented Aug 15, 2017 at 17:58
  • The TeXify App doesn't seem to work when including inline mathjax for markdown enumerated items.
    – user32882
    Commented Jul 20, 2019 at 11:20
  • Hi, are there any dvisvgm binaries for Mac
    – juanmf
    Commented May 26, 2022 at 19:37
29

Since May 2022, this has been officially supported:

Inline:

Where $x = 0$, evaluate $x + 1$

Blocks:

Where
$$x = 0$$

Evaluate
$$x + 1$$
1
  • 1
    It works for me this way, github now accept well enogh this way
    – F4NT0
    Commented Sep 5, 2022 at 14:09
17

One can also use this online editor: https://www.codecogs.com/latex/eqneditor.php which generates SVG files on the fly. You can put a link in your document like this: ![](https://latex.codecogs.com/svg.latex?y%3Dx%5E2) which results in: .

0
14

I test some solution proposed by others and I would like to recommend TeXify created and proposed in comment by agurodriguez and further described by Tom Hale - I would like develop his answer and give some reason why this is very good solution:

  • TeXify is wrapper of Readme2Tex (mention in Lee answer). To use Readme2Tex you must install a lot of software in your local machine (python, latex, ...) - but TeXify is github plugin so you don't need to install anything in your local machine - you only need to online installation that plugin in you github account by pressing one button and choose repositories for which TeXify will have read/write access to parse your tex formulas and generate pictures.
  • When in your repository you create or update *.tex.md file, the TeXify will detect changes and generate *.md file where latex formulas will be exchanged by its pictures saved in tex directory in your repo. So if you create README.tex.md file then TeXify will generate README.md with pictures instead tex formulas. So parsing tex formulas and generate documentation is done automagically on each commit&push :)
  • Because all your formulas are changed into pictures in tex directory and README.md file use links to that pictures, you can even uninstall TeXify and all your old documentation will still works :). The tex directory and *.tex.md files will stay on repository so you have access to your original latex formulas and pictures (you can also safely store in tex directory your other documentation pictures "made by hand" - TeXify will not touch them).
  • You can use equations latex syntax directly in README.tex.md file (without loosing .md markdown syntax) which is very handy. Julii in his answer proposed to use special links (with formulas) to external service e.g . http://latex.codecogs.com/gif.latex?s%3D%5Ctext%20%7B%20sensor%20reading%20%7D which is good however has some drawbacks: the formulas in links are not easy (handy) to read and update, and if there will be some problem with that third-party service your old documentation will stop work... In TeXify your old documentation will works always even if you uninstall that plugin (because all your pictures generated from latex formulas are stay in repo in tex directory).
  • The Yuchao Jiang in his answer, proposed to use Jupyter Notebook which is also nice however have som drawbacks: you cannot use formulas directly in README.md file, you need to make link there to other file *.ipynb in your repo which contains latex (MathJax) formulas. The file *.ipynb format is JSON which is not handy to maintain (e.g. Gist don't show detailed error with line number in *.ipynb file when you forgot to put comma in proper place...).

Here is link to some of my repo where I use TeXify for which documentation was generated from README.tex.md file.

Update

Today 2020.12.13 I realised that TeXify plugin stop working - even after reinstallation :(

3
  • @Royi I don't know Commented Jan 16, 2019 at 10:50
  • 1
    It's nice but how do you deal with a tons of unused garbage svg images in /tex folder?
    – Serge P.
    Commented Mar 21, 2019 at 6:04
  • 1
    @SergeP. delate all and push? Commented Mar 21, 2019 at 10:52
8

For automatic conversion upon push to GitHub, take a look at the TeXify app:

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.

4
  • 1
    This work is by @agurodriguez who mentions it in a comment above
    – icc97
    Commented Jan 13, 2019 at 14:12
  • 1
    @icc97 yes, but agurodriguez not create answer (and I will probably never notice his comment). Because Tom create answer (~1 year after agurodriguez) I notce that TeXify exists and it allows me to use TeXify and write my own answer base on this. So it was good :) Commented Jan 16, 2019 at 12:09
  • 3
    @KamilKiełczewski There's nothing wrong with this answer, I'm just mentioning that TeXify was created by a SO user because of this thread, which is pretty cool.
    – icc97
    Commented Jan 18, 2019 at 6:54
  • I am using TeXify on my readme but, for some reason, the rendering is jumping lines almost every time where there is a $...$ in the text. Any clues why? This is the repo: github.com/brunoconteleite/Spatial-Model-Solver Commented Sep 14, 2019 at 12:10
4

I just published a new version of xhub, a browser extension that renders LaTeX (and other things) in GitHub pages.

Cons:

  • You have to install the extension once.

Pros:

  • No need to set up anything.
  • Just write Markdown with math
    Display math:
    ```math
    e^{i\pi} + 1 = 0
    ```
    and line math $`a^2 + b^2 = c^2`$.
    
    (Syntax like on GitLab.)
  • Works on light and dark background. (Math has text-color)
  • You can copy-and-paste the math just like text

As an example, check out this GitHub README:

enter image description here

2
  • 1
    Cool, but doesn't render the maths to other visitors (like me), which is the point of the README...
    – Jthorpe
    Commented Apr 1, 2022 at 19:49
  • Right, only for other visitors who have the extension installed. Commented Apr 2, 2022 at 9:19
1

You can get a continuous integration service (e.g. Travis CI) to render LaTeX and commit results to github. CI will deploy a "cloud" worker after each new commit. The worker compiles your document into pdf and either cuses ImageMagick to convert it to an image or uses PanDoc to attempt LaTeX->HTML conversion where success may vary depending on your document. Worker then commits image or html to your repository from where it can be shown in your readme.

Sample TravisCi config that builds a PDF, converts it to a PNG and commits it to a static location in your repo is pasted below. You would need to add a line that fetches pdfconverts PDF to an image

sudo: required
dist: trusty
os: linux
language: generic
services: docker
env:
  global:
  - GIT_NAME: Travis CI
  - GIT_EMAIL: [email protected]
  - TRAVIS_REPO_SLUG: your-github-username/your-repo
  - GIT_BRANCH: master
# I recommend storing your GitHub Access token as a secret key in a Travis CI environment variable, for example $GH_TOKEN.
  - secure: ${GH_TOKEN}
script:
- wget https://raw.githubusercontent.com/blang/latex-docker/master/latexdockercmd.sh
- chmod +x latexdockercmd.sh
- "./latexdockercmd.sh latexmk -cd -f -interaction=batchmode -pdf yourdocument.tex -outdir=$TRAVIS_BUILD_DIR/"
- cd $TRAVIS_BUILD_DIR
- convert -density 300 -quality 90 yourdocument.pdf yourdocument.png
- git checkout --orphan $TRAVIS_BRANCH-pdf
- git rm -rf .
- git add -f yourdoc*.png
- git -c user.name='travis' -c user.email='travis' commit -m "updated PDF"
# note we are again using GitHub access key stored in the CI environment variable
- git push -q -f https://your-github-username:[email protected]/$TRAVIS_REPO_SLUG $TRAVIS_BRANCH-pdf
notifications:
  email: false

This Travis Ci configuration launches a Ubuntu worker downloads a latex docker image, compiles your document to pdf and commits it to a branch called branchanme-pdf.

For more examples see this github repo and its accompanying sx discussion, PanDoc example, https://dfm.io/posts/travis-latex/, and this post on Medium.

1

I have been looking around and found that this answer in another question works best for me. i.e. use githubcontent math renderer, e.g. to display:

enter link description here

Use this link Beware of the latex needs to be url encoded, but otherwise work quite well for me.

0

If you are having issues with https://www.codecogs.com/latex/eqneditor.php, I found that https://alexanderrodin.com/github-latex-markdown/ worked for me. It generates the Markdown code you need, so you just cut and paste it into your README.md document.

0

You may also take a look on my tool latexMarkdown2Markdown which convert LaTeX to SVG and generate a table of content with chapter numbering.

0

Good news! According to this blogpost, now GitHub supports Mathjax in readme files.

You can use in-line LaTeX inspired syntax using $ delimiters, or in-blocks using $$ delimiters.

1
0

Writing inline expressions:

This sentence uses $ delimiters to show math inline: $\sqrt{3x-1}+(1+x)^2$

Writing expressions as blocks:

The Cauchy-Schwarz Inequality

$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$

Source: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions

-1

You can use markdowns, e.g.

![equ](https://latex.codecogs.com/gif.latex?log(y)=\beta_0&space;&plus;&space;\beta_1&space;x&space;&plus;&space;u)

Code can be typed here: https://www.codecogs.com/latex/eqneditor.php.

-3

Edit: As germanium pointed out, it does not work for README.md but other git pages though no explanation is available. My quick solution is this

step 1. Add latex to your .md file

$$x=\sqrt{2}$$

Note: math eqns must be in $$...$$ or \\(... \\).

step 2. Add the following to your scripts.html or theme file (append this code at the end)

<script type="text/javascript" async

src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML">

Done!. See your eq. by loading the page.

4
  • 3
    What scripts.html file? I can't find any reference to this as a github feature.
    – Jay Lemmon
    Commented Nov 25, 2019 at 15:41
  • do you have theme file ( Jeykyll theme file)? This code is for displaying latex in git pages.
    – CKM
    Commented Nov 26, 2019 at 13:55
  • 6
    Should clarify that this only works for git pages, not for README.md in regular repo.
    – germanium
    Commented Jan 16, 2020 at 21:18
  • @germanium do you have any explanation on why it does not work on README.md? If you read my comment above, it says git pages.
    – CKM
    Commented Apr 22, 2021 at 11:51

Not the answer you're looking for? Browse other questions tagged or ask your own question.