Latex rendering in README.md on Github

Question

Is there a way to render LaTex in README.md in the GitHub repository? I searched for it and searched for a stack overflow, but none of the related answers seem possible.

Answer 1

For short expressions and not-so-pretty maths, you can use the built-in HTML code to output your latex maths to codecs, and then embed the resulting image. Here is 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 lead to something like the following

Update: This works great in Eclipse, but unfortunately not in GitHub. The only workaround is as follows:

Take your latex equation and go to http://www.codecogs.com/latex/eqneditor.php. At the bottom of the area where your equation is displayed, there is a small drop-down menu, select the encoded URL and paste it into your file. GitHub markdown as follows:

 ![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) 

Answer 2

Readme2Tex

I worked on a script that automates most of the clutter because you easily type a LaTeX set into a Github markdown: https://github.com/leegao/readme2tex

There are several issues with rendering LaTeX for Github. Firstly, Github markdowns are a variety of tags and most attributes. This does not mean that Javascript-based libraries (like Mathjax) nor CSS-style.

The natural solution, apparently, is to embed images of precompiled equations. However, you will soon realize that LaTeX does more than just convert formulas in dollars into images.

Just embedding images from online compilers gives this unnatural look at your document. In fact, I would say that it is even more readable in your everyday math slang x ^ 2 than jumping .

I believe it is important that your documents are typed in a natural and understandable way. That's why I wrote a script that, in addition to compiling formulas in images, also ensures that the resulting image is correctly set and aligned with the rest of the text.

For example, here is an excerpt from a .md file regarding some of the enumerated regular expression set properties using readme2tex :

As expected, the set of equations at the top is set by running the appropriate align* environment

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

Note that while inline equations ($ ... $) work with text, the displayed equations (those that are limited to \begin{ENV}...\end{ENV} or $$...$$ ) are centered. This makes it easier for people who are already used to LaTeX to be productive.

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

Answer 3

My trick is to use a Jupyter laptop.

GitHub has built-in support for rendering .ipynb files. You can write inline and display LaTeX code in notepad, and GitHub will provide it to you.

Here is an example notebook file: https://gist.github.com/cyhsutw/d5983d166fb70ff651f027b2aa56ee4e

Answer 4

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

Answer 5

I load the equation repositories into Gitlab because it has built-in LaTeX support in .md files:

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

The syntax for embedded latex is $'\sqrt{2}'$ .

Gitlab displays equations using JavaScript in a browser instead of displaying images, which improves the quality of the equations.

More info here .

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

Answer 6

For automatic conversion when downloading to GitHub, take a look at the TeXify application:

A GitHub application that searches for files with the * .tex.md extension in your files and displays their TeX expressions as SVG images.

How it works (from the source repository ):

Whenever you click, TeXify will launch and search for * .tex.md files in your last commit. For each of them, it will run readme2tex, which will accept LaTeX expressions enclosed in dollar signs, convert it to simple SVG images, and then save the output to an .md extension file (this 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 new SVG images are then captured and returned to the repository.

Answer 7

I am testing some solution suggested by others, and I would like to recommend TeXify, created and proposed in the agurodriguez comment and further described by Tom Hale - I would like to develop his answer and explain why this is a very good solution:

• TeXify is a Readme2Tex shell ( mention in Lee's answer ). To use Readme2Tex, you have to install a large amount of software on your local computer (python, latex, ...), but TeXify is a github plugin, so you do not need to install anything on the local computer - you only need an online installation that connect your github account with a single click and select the repositories for which TeXify will have read / write access to analyze your text formulas and create images.
• When you create or update the *.tex.md file in your repository, TeXify will detect the changes and generate a *.md file which will replace the latex formulas with its images stored in the tex directory in your repo. Therefore, if you create the README.tex.md file, TeXify will generate README.md with images instead of text formulas. Thus, parsing tex formulas and creating documentation is performed automatically with every commit and click :)
• Since all your formulas turn into drawings in the tex directory and links to these drawings are used in the README.md file, you can even delete TeXify, and all your old documentation will still work :). The tex directory and *.tex.md files will remain in the repository, so you have access to the source formulas and latex drawings (you can also safely store your other manual images in the tex directory - TeXify does not touch them),
• You can use the latex equation syntax directly in the README.tex.md file (without losing the markdown .md syntax), which is very convenient . Julius in his answer suggested using special links (with formulas) to an external service, for example. http://latex.codecogs.com/gif.latex?s%3D%5Ctext%20%7B%20sensor%20reading%20%7D which is good, however, has some disadvantages: the formulas in the links are not easy (convenient) to read and update, and if there is any problem with this third-party service, your old documentation will stop working ... In TeXify, your old documentation will always work, even if you remove this plugin (because all your images created from latex formulas remain in the repo in tex directory).
• Yuchao Jiang in his answer suggested using Jupyter Notebook, which is also not bad, but it has some disadvantages: you cannot use formulas directly in the README.md file, you need to make a link to another * .ipynb file in your repo that contains latex (MathJax ) formulas. The * .ipynb file format is JSON, which is not very convenient to maintain (for example, Gist does not show a detailed error with the line number in the * .ipynb file when you forgot to put a comma in the right place ...).

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

Answer 8

You can use the awesome plugin for Chrome - https://chrome.google.com/webstore/detail/mathjax-plugin-for-imtqy.comemnmodlmafdkllaclgeombjnmnbima