在Github上的README.md中进行乳胶渲染

Question

有没有办法在GitHub存储库中的README.md中呈现LaTex？我用谷歌搜索并搜索堆栈溢出但没有相关的答案似乎可行。

Answer 1

对于简短的表达式而不是那么花哨的数学，你可以使用内联HTML在代码架上获得乳胶渲染数学，然后嵌入生成的图像。这是一个例子：

- <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 " />

这会产生类似下一个的东西

更新：这在eclipse中效果很好但不幸的是在github中没有。唯一的解决方法是下一个：

拿你的乳胶方程式转到http://www.codecogs.com/latex/eqneditor.php，在显示公式的区域的底部有一个小的下拉菜单，选择URL编码，然后将其粘贴到你的github markdown中：

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

我一直在制作一个脚本，可以自动完成将LaTeX很好地排版到Github风格的降价中的大部分内容：https://github.com/leegao/readme2tex

渲染LaTeX for Github有一些挑战。首先，Github风味的markdown剥离了大多数标签和大多数属性。这意味着没有基于Javascript的库（如Mathjax）或任何CSS样式。

然后，自然解决方案似乎是嵌入预编译方程的图像。但是，您很快就会意识到，LaTeX不仅仅是将美元符号封闭的公式转换成图像。

简单地嵌入来自在线编译器的图像会给文档带来非常不自然的外观。事实上，我认为它在你的日常x ^ 2数学俚语中比在跳跃时更具可读性。

我相信确保您的文档以自然和可读的方式排版非常重要。这就是为什么我编写了一个脚本，除了将公式编译成图像之外，还确保生成的图像正确匹配并与文本的其余部分对齐。

例如，这里是一个.md文件的摘录，关于使用readme2tex排版的正则表达式的一些枚举属性：

正如您所料，顶部的方程组通过启动相应的align*环境来指定

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

请注意，虽然内联方程（$ ... $）与文本一起运行，但显示方程（由\begin{ENV}...\end{ENV}或$$...$$分隔的方程）居中。这使已经习惯了LaTeX的人们能够轻松地保持工作效率。

如果这听起来像是可以帮助的东西，请务必检查出来。 https://github.com/leegao/readme2tex

Answer 3

我的诀窍是使用Jupyter笔记本。

GitHub内置支持渲染.ipynb文件。您可以在笔记本中编写内联并显示LaTeX代码，GitHub将为您呈现。

这是一个示例笔记本文件：https://gist.github.com/cyhsutw/d5983d166fb70ff651f027b2aa56ee4e

Answer 4

也可以使用这个在线编辑器：https://www.codecogs.com/latex/eqneditor.php，它可以动态生成SVG文件。您可以在文档中添加如下链接：![](https://latex.codecogs.com/svg.latex?y%3Dx%5E2)，其结果为：。

Answer 5

我将带有方程式的存储库上传到Gitlab，因为它在.md文件中对LaTeX有本机支持：

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

内联乳胶的语法是$`\sqrt{2}`$。

Gitlab在浏览器中使用JavaScript渲染方程而不是显示图像，这提高了方程的质量。

更多信息here。

让我们希望Github将来也能实现这一点。

Answer 6

我测试了其他人提出的一些解决方案，我想推荐TeXify在agurodriguez评论中创建并提出并由Tom Hale进一步描述 - 我想提出他的答案，并给出一些理由，为什么这是非常好的解决方案：

• TeXify是Readme2Tex的包装（在Lee answer中提到）。要使用Readme2Tex，您必须在本地计算机上安装许多软件（python，latex，...） - 但TeXify是github插件，因此您无需在本地计算机上安装任何东西 - 您只需在线安装即可通过按下一个button插入你的github帐户并选择TeXify将具有读/写访问权限的存储库来解析你的tex公式并生成图片。
• 当您在存储库中创建或更新*.tex.md文件时，TeXify将检测更改并生成*.md文件，其中乳胶公式将通过保存在repo中的tex目录中的图片进行交换。因此，如果您创建README.tex.md文件，那么TeXify将生成带有图片而不是tex公式的README.md。所以解析tex公式和生成文档是在每次提交和推送时自动完成的:)
• 因为所有的公式都被更改为tex目录中的图片，而README.md文件使用指向该图片的链接，您甚至可以卸载TeXify，所有旧文档仍然可以工作:)。 tex目录和*.tex.md文件将保留在存储库中，因此您可以访问原始乳胶配方和图片（您还可以安全地存储在tex目录中，您手工制作的其他文档图片 - TeXify不会触及它们）。
• 您可以直接在README.tex.md文件中使用方程乳胶语法（不会丢失.md降价语法），这非常方便。 Julii in his answer建议使用特殊链接（带公式）来进行外部服务，例如。然而，http://latex.codecogs.com/gif.latex?s%3D%5Ctext%20%7B%20sensor%20reading%20%7D有一些缺点：链接中的公式不容易（方便）阅读和更新，如果第三方服务会有一些问题，你的旧文档将停止工作...在TeXify你的旧即使您卸载该插件，文档也会一直有效（因为从乳胶公式生成的所有图片都保留在tex目录中的repo中）。
• Yuchao Jiang在他的回答中，建议使用Jupyter Notebook，这也很好但是有som的缺点：你不能直接在README.md文件中使用公式，你需要在你的repo中包含乳胶（MathJax）的其他文件* .ipynb链接）公式。文件* .ipynb格式是JSON，维护起来不方便（例如，当忘记将逗号放在适当的位置时，Gist不会显示* .ipynb文件中行号的详细错误...）。

Here is link到我的一些repo，我使用Tezify从README.tex.md文件生成文档。

Answer 7

要在推送到GitHub时自动转换，请查看TeXify应用程序：

GitHub应用程序，用于查找扩展名为* .tex.md的文件，并将其TeX表达式呈现为SVG图像

它是如何工作的（来自source repository）：

无论何时推送，TeXify都会在上次提交时运行并搜索* .tex.md文件。对于其中的每一个，它将运行readme2tex，它将把美元符号之间的LaTeX表达式括起来，将其转换为普通的SVG图像，然后将输出保存到.md扩展文件中（这意味着名为README.tex.md的文件）将被处理，输出将保存为README.md）。之后，输出文件和新的SVG图像将被提交并推回到您的仓库。