readme2tex

Renders LaTeX for Github Readmes

Make sure that pdflatex is installed on your system.

readme2tex is a Python script that "texifies" your readme. It takes in Github Markdown and replaces anything enclosed between dollar signs with rendered <img alt="$\text{\LaTeX}$" src="svgs/c068b57af6b6fa949824f73dcb828783.png?invert_in_darkmode" align=middle width="42.05817pt" height="22.407pt"/>.

In addition, while other Github TeX renderers tend to give a jumpy look to the compiled text,

readme2tex ensures that inline mathematical expressions are properly aligned with the rest of the text to give a more natural look to the document. For example, this formula <img alt="$\frac{dy}{dx}$" src="svgs/24a7d013bfb0af0838f476055fc6e1ef.png?invert_in_darkmode" align=middle width="14.297415pt" height="30.58869pt"/> is preprocessed so that it lines up at the correct baseline for the text. This is the one salient feature of this package compared to the others out there.

Installation

Make sure that you have Python 2.7 or above and pip installed. In addition, you'll need to have the programs latex and dvisvgm on your PATH. In addition, you'll need to pre-install the geometry package in <img alt="$\text{\LaTeX}$" src="svgs/c068b57af6b6fa949824f73dcb828783.png?invert_in_darkmode" align=middle width="42.05817pt" height="22.407pt"/>.

To install readme2tex, you'll need to run

sudo pip install readme2tex

or, if you want to try out the bleeding edge,

git clone https://github.com/leegao/readme2tex
cd readme2tex
python setup.py develop

To compile INPUT.md and render all of its formulas, run

python -m readme2tex --output README.md INPUT.md

If you want to do this automatically for every commit of INPUT.md, you can use the --add-git-hook command once to set up the post-commit hook, like so

git stash --include-untracked
git branch svgs # if this isn't already there

python -m readme2tex --output README.md --branch svgs --usepackage tikz INPUT.md --add-git-hook

# modify INPUT.md

git add INPUT.md
git commit -a -m "updated readme"

git stash pop

and every git commit that touches INPUT.md from now on will allow you to automatically run readme2tex on it, saving you from having to remember how readme2tex works. The caveat is that if you use a GUI to interact with git, things might get a bit wonky. In particular, readme2tex will just assume that you're fine with all of the changes and won't prompt you for verification like it does on the terminal.

You can uninstall the hook by deleting .git/hooks/post-commit. See python -m readme2tex --help for a list of what you can do in readme2tex.

Examples:

Here's a display level formula

The code that was used to render this formula is just

$$
\frac{n!}{k!(n-k)!} = {n \choose k}
$$

Note: you can escape $ so that they don't render.

Here's an inline formula.

It is well known that if <img alt="$ax^2 + bx + c =0$" src="svgs/162f63774d8a882cc15ae1301cfd8ac0.png?invert_in_darkmode" align=middle width="119.01186pt" height="26.70657pt"/>, then <img alt="$x = \frac{-b \pm \sqrt{b^2- 4ac}}{2a}$" src="svgs/584fa2612b78129d140fb208e9d76ae9.png?invert_in_darkmode" align=middle width="112.3584pt" height="33.20526pt"/>.

The code that was used to render this is:

It is well known that if $ax^2 + bx + c = 0$, then $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.

Notice that the formulas line up with the baseline of the text, even when the height of these two images are different.

Sometimes, you might run into formulas that are bottom-heavy, like <img alt="$x^2\sum\limits_{3^{n^{n^{n}}}}$" src="svgs/4cb4ead947a07837121937c807973436.png?invert_in_darkmode" align=middle width="47.639295pt" height="37.03194pt"/>. Here, readme2tex can compute the correct offset to align this formula to the baseline of your paragraph of text as well.

Tikz (Courtesy of http://www.texample.net/)

Did you notice the picture at the top of this page? That was also generated by <img alt="$\text{\LaTeX}$" src="svgs/c068b57af6b6fa949824f73dcb828783.png?invert_in_darkmode" align=middle width="42.05817pt" height="22.407pt"/>. readme2tex is capable of handling Tikz code. For reference, the picture

is given by the tikz code

\begin{tikzpicture}
\newcounter{density}
\setcounter{density}{20}
    \def\couleur{red}
    \path[coordinate] (0,0)  coordinate(A)
                ++( 60:6cm) coordinate(B)
                ++(-60:6cm) coordinate(C);
    \draw[fill=\couleur!\thedensity] (A) -- (B) -- (C) -- cycle;
    \foreach \x in {1,...,15}{%
        \pgfmathsetcounter{density}{\thedensity+10}
        \setcounter{density}{\thedensity}
        \path[coordinate] coordinate(X) at (A){};
        \path[coordinate] (A) -- (B) coordinate[pos=.15](A)
                            -- (C) coordinate[pos=.15](B)
                            -- (X) coordinate[pos=.15](C);
        \draw[fill=\couleur!\thedensity] (A)--(B)--(C)--cycle;
    }
\end{tikzpicture}

We can see a few other examples, such as this graphical proof of the Pythagorean Theorem.

How about a few snowflakes?

<img alt="\begin{center}
\usetikzlibrary{lindenmayersystems}

\pgfdeclarelindenmayersystem{A}{
 \rule{F -> FF[+F][-F]}
}

\pgfdeclarelindenmayersystem{B}{
 \rule{F -> ffF[++FF][--FF]}
}

\pgfdeclarelindenmayersystem{C}{
 \symbol{G}{\pgflsystemdrawforward}
 \rule{F -> F[+F][-F]FG[+F][-F]FG}
}

\pgfdeclarelindenmayersystem{D}{
 \symbol{G}{\pgflsystemdrawforward}
 \symbol{H}{\pgflsystemdrawforward}
 \rule{F -> H[+HG][-HG]G}
 \rule{G -> HF}
}

\tikzset{
 type/.style={l-system={#1, axiom=F,order=3,step=4p

Readme2tex

Install / Use

README

readme2tex

Installation

Examples:

Tikz (Courtesy of http://www.texample.net/)