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 andreplaces anything enclosed between dollar signs with rendered .
In addition, while other Github TeX renderers tend to give a jumpy look to the compiled text,
readme2tex
ensures that inline mathematical expressionsare properly aligned with the rest of the text to give a more natural look to the document. For example,this formula 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.
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 .
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 toset 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, savingyou from having to remember how readme2tex
works. The caveat is that if you use a GUI to interact with git, thingsmight get a bit wonky. In particular, readme2tex
will just assume that you're fine with all of the changes and won'tprompt 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 listof what you can do in readme2tex
.
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.
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 . Here, readme2tex
can compute the correct offset to align this formula to the baseline of your paragraph of text as well.
Did you notice the picture at the top of this page? That was also generated by . readme2tex
is capable ofhandling 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?
python -m readme2tex --output README.md [READOTHER.md]
It will then look for a file called readother.md
and compile it down to a readable Github-readydocument.
In addition, you can specify other arguments to render.py
, such as:
--readme READOTHER.md
The raw readme to process. Defaults to READOTHER.md
.--output README.md
The processed readme.md file. Defaults to README_GH.md
.--usepackage tikz
Addition packages to use during compilation. You can specify this multiple times.--svgdir svgs/
The directory to store the output svgs. The default is svgs/
--branch master
Experimental Which branch to store the svgs into, the default is just master.--username username
Your github username. This is optional, and render.py
will try to infer this for you.--project project
The current github project. This is also optional.--nocdn
Ticking this will use relative paths for the output images. Defaults to False.--htmlize
Ticking this will output a md.html
file so you can preview what the output looks like. Defaults to False.--valign
Ticking this will use the valign
trick (detailed below) instead. See the caveats section for tradeoffs.--rerender
Ticking this will force a recompilation of all formulas even if they are already cached.--bustcache
Ticking this will ensure that Github renews its image cache. Github may sometimes take up to an hour for changed images to reappear. This is usually not necessary unless you've made stylistic changes.--add-git-hook
Ticking this will generate a post-commit hook for git that runs readme2tex with the rest of the specified arguments after each git commit
.--pngtrick
Ticking this will generate png
files instead of svgs
for the formulas.My usual workflow is to create a secondary branch just for the compiled svgs. You can accomplish this via
python -m readme2tex --branch svgs --output README.md
However, be careful with this command, since it will switch over to the svgs
branch without any input from you.
If you're on a private repository or you want to, for whatever reason, use relative paths to resolve your images, you cando so by using the combination
python -m readme2tex --branch master --nocdn --pngtrick ...
which will output pngs
relative to your README.md
.
Due to security considerations, Github will not resolve svgs
relatively, which means that private repositories willbe locked out of the usual svg
workflow. Using the --branch master --nocdn --pngtrick
combination will get aroundthis restriction.
If your Tikz drawings don't show up, there's a good chance that you either don't have Ghostscript installed ordvisvgm
isn't picking it up for whatever reason. This is most likely to happen on some installations of TexLiveon OSX.
Check to see if ps
is included in the list when you run
# dvisvgm -l
bgcolor background color special
color complete support of color specials
dvisvgm special set for embedding raw SVG snippets
em line drawing statements of the emTeX special set
html hyperref specials
pdf pdfTeX font map specials
ps dvips PostScript specials <<<
tpic TPIC specials
If not, try installing it (either apt-get
, yum
, or brew
). Furthermore, if you are on OSX, make sure to add thefollowing to your ~/.bash_profile
export LIBGS=/usr/local/lib/libgs.dylib
where /usr/local/lib/libgs.dylib
is the location where libgs.dylib
is installed.
Make sure that if you have a <p>...</p>
tag somewhere, you leave at least one blank line after the closing tag.
--add-git-hook
, but the post-commit hook isn't running after committing.chmod +x .git/hooks/post-commit
readme2tex
and got strange image srcs or got images that won't resolveTry running readme2tex
with
python -m readme2tex ... --username GITHUB_USERNAME --project PROJECT_NAME
readme2tex
and got a traceback somewhere.Unfortunately, this script still has a few kinks and bugs that I need to iron out. In the mean time, if the pypi
releasesaren't working for you, you should switch over to the development version to see if the bugs have been squashed:
git clone https://github.com/leegao/readme2tex
cd readme2tex
python setup.py develop
By prepending every inline formula with an anchor. During post-processing, we can isolate the anchor, whichis fixed at the baseline, and crop it out. It's super clowny, but it does the job.
Github does not allow you to pass in custom style attributes to your images. While this is useful for security purposes,it makes it incredibly difficult to ensure that images will align correctly to the text. readme2tex
circumvents thisusing one of two tricks:
valign=offset
works for img
tags as well. This allows us to shift the image directly.Unfortunately, this is not supported within any of the other major browsers, therefore this mode is not enabled bydefault.align=middle
attribute will vertically center an image. However, thedefinition of the vertical "center" is different. In particular, for Chrome, Firefox, (and probably Safari), that centeris the exact middle of the image. For IE and Edge however, the center is about 5 pixels (the height of a lower-case character)above the exact center. Since this looks great for non-IE browsers, and reasonably good on Edge, this is the defaultrendering method. The trick here is to pad either the top or the bottom of the image with extra spaces until thebaseline of the formula is at the center. For most formulas, this works great. However, if you have a tall formula,like , you'll notice that there might be a lotof slack vertical spacing between these lines. If this is a deal-breaker for you, you can always try the --valign True
mode. For most inline formulas, this is usually a non-issue.Make sure that you have the tikz
and the xcolor
packages installed locally.
python -m readme2tex --usepackage "tikz" --usepackage "xcolor" --output README.md --branch svgs
and of course
python -m readme2tex --usepackage "tikz" --usepackage "xcolor" --output README.md --branch svgs --add-git-hook
For the png
relative mode, use
python -m readme2tex --usepackage "tikz" --usepackage "xcolor" --output README.md --branch master --nocdn --pngtrick
原文链接:http://www.readern.com/sublime-text-latex-chinese-under-mac.html LaTex就不多做介绍了,其实一般人用到的机会也不多(包括我)。只是这段时间在Coursera上学课程的时候,偶尔需要,所以从零开始摸索了一下,也顺便进一步发现了Sublime Text的强大。 MAC上的LaTex部署,一般是两条思路,一个是直接安装MacT
具体步骤 1. 通过Python安装readme2tex sudo pip install readme2tex 2.去已经建立好了的Github repository文件夹中 cd gitrepository python3 -m readme2tex --nocdn --output README.md INPUT.md 3. push即可。 4. 问题: $$中的中文信息无法显示
其实有官方文档: https://www.tug.org/texlive/doc/texlive-zh-cn/texlive-zh-cn.pdf 此外,在镜像站下载的iso中也有readme。 首先,在镜像装载页执行 sudo perl install-tl 然后按提示 enter:I 安装完成。 之后安装texstudio sudo apt-get install texstudio 即可。
val textFile = sc.textFile("/usr/local/spark/README.md") textFile: org.apache.spark.rdd.RDD[String] = /usr/local/spark/README.md MapPartitionsRDD[3] at textFile at <console>:24 scala> textFile.count(