Github上README.md文件中的Latex渲染

Question

有没有办法在GitHub存储库的README.md中呈现LaTex？我已经搜索了Google和Stack Overflow，但似乎没有一个可行的答案。

- user90593

---

这是不可能直接实现的。您是否有特定需要使用LaTex的事情？例如，如果您想要数学方程式，可能可以通过一些特定的技巧来实现。告诉我们您想呈现什么，也许有人能够指出一个解决方法。 - Waylan

是的，我想要数学方程和对齐方程，以及内联数学符号。就这样。 - user90593

请参考此相关帖子: 如何在GitHub的Markdown中显示数学公式（非GitHub的博客）。 - Waylan

你考虑过使用Jupyter笔记本吗？现在甚至可以插入Python代码 ;) - Charlie Parker

GitHub自2022年5月起支持Latex/MathJax。 - VonC

Answer 1

对于简短的表达和不太复杂的数学公式，你可以使用内联HTML来在codecogs上渲染你的latex数学公式，然后嵌入生成的图片。这里是一个例子：

- <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中不起作用。唯一的解决办法是下面这样：

将你的LaTeX公式复制到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)

- Juli

---

我建议使用 https://latex.codecogs.com/png.latex 替代 https://latex.codecogs.com/gif.latex；前者可以生成更高质量的图片！ - Steffo

您可以使用latex.codecogs.com/svg.latex，它是分辨率无关的。 - lizardfireman

有效，但在用户使用暗色或调暗主题时效果不佳。在URL中的问号后插入“%5Cbg_white%20”，即可获取黑底白字版本。 - Jan

Answer 2

我将带有方程式的代码库上传到Gitlab，因为它原生支持在.md文件中使用LaTeX：

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

内联LaTeX的语法为$`\sqrt{2}`$。

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

更多信息请点击此处。

希望Github将来也会实现这一点。

- Evgenii

---

@RylanSchaeffer <pre xml:lang="latex">\sqrt{2}</pre> - LinconFive

@LinconFive 谢谢，但你能解释一下如何使用吗？我刚刚将这个 pre 代码复制粘贴到 Github 上的 README.md 中，但它没有起作用（只显示了 \sqrt{2} 文本）。 - Evgenii

@LinconFive 我认为它甚至在纯HTML5中也无法工作。 - M. Al Jumaily

Answer 3

我的技巧是使用Jupyter Notebook。

GitHub内置支持渲染.ipynb文件。你可以在notebook中编写行内和显示LaTeX代码，GitHub将为你呈现出来。

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

- Yuchao Jiang

Answer 4

Readme2Tex

我一直在开发一个脚本，可以自动化大部分的工作，使得 LaTeX 可以很好地排版到 Github 风格的 markdown 中：https://github.com/leegao/readme2tex

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

因此，自然的解决方案似乎是嵌入预编译公式的图像。然而，您很快就会意识到，LaTeX 所做的不仅仅是将用美元符号括起来的公式转换为图像。

从在线编译器嵌入图像会使您的文档看起来非常不自然。实际上，我认为它甚至比跳动的在您的日常x^2数学俚语中更易读。

我认为确保文档以自然且易读的方式排版很重要。这就是为什么我编写了一个脚本，除了将公式编译成图像外，还确保生成的图像适当地适配并对齐到其余文本。

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

就像你所预期的那样，顶部的方程组是通过启动相应的align*环境来指定的。

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

请注意，虽然行内公式（$...$）与文本一起运行，但显示公式（由\begin{ENV}...\end{ENV}或$$...$$分隔的公式）是居中的。这使得那些已经习惯于LaTeX的人们可以保持高效生产力。

如果您认为这听起来有帮助，请务必查看。https://github.com/leegao/readme2tex

- Lee

---

基于这项工作，我创建了一个 GitHub 应用程序，自动化了渲染过程，并在每次推送时触发它。我认为这很有用，因此分享链接给那些想尝试的人：https://github.com/agurz/github-texify - agurodriguez

当在Markdown枚举项中包含行内MathJax时，TeXify应用程序似乎无法正常工作。 - user32882

你好，Mac上有没有dvisvgm二进制文件？ - juanmf

Answer 5

自2022年5月起，以下内容已正式支持：数学公式和高级格式。

内联：

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

块：

Where
$$x = 0$$

Evaluate
$$x + 1$$

- Richie Bendall

---

这种方式对我有效，现在Github也很好地接受了这种方式。 - F4NT0

Answer 6

还可以使用这个在线编辑器：https://www.codecogs.com/latex/eqneditor.php，它可以即时生成SVG文件。您可以像这样在文档中插入一个链接：![](https://latex.codecogs.com/svg.latex?y%3Dx%5E2)，结果如下所示：

- Dylan Richard Muir

Answer 7

我测试了一些别人提出的解决方案，我想推荐agurodriguez在评论中创建和提出的TeXify，并由Tom Hale进一步描述 - 我想发展他的答案并给出一些原因，说明这是一个非常好的解决方案：

TeXify是Lee answer中提到的Readme2Tex的包装器。要使用Readme2Tex，您必须在本地计算机上安装许多软件（如python、latex等），但TeXify是github插件，所以您不需要在本地计算机上安装任何东西——您只需要按一个button在线安装该插件，并选择为其提供读/写访问权限以解析您的tex公式并生成图片的存储库。

当您在存储库中创建或更新*.tex.md文件时，TeXify会检测更改并生成*.md文件，其中latex公式将被其图片替换，这些图片保存在存储库中的tex目录中。因此，如果您创建README.tex.md文件，则TeXify将生成README.md文件，其中包含图片而不是tex公式。因此，解析tex公式并生成文档是自动完成的，每次提交和推送都会进行：）

由于所有公式都在tex目录中更改为图片，并且README.md文件使用链接指向那些图片，即使卸载TeXify，您所有旧的文档仍将正常工作：）。tex目录和*.tex.md文件将保留在存储库中，因此您可以访问原始的latex公式和图片（您还可以安全地将其他手工制作的文档图片存储在tex目录中——TeXify不会触及它们）。 您可以直接在README.tex.md文件中使用方程式latex语法（而不会失去.md markdown语法），这非常方便。Julii in his answer建议使用特殊链接（带有公式）到外部服务，例如http://latex.codecogs.com/gif.latex?s%3D%5Ctext%20%7B%20sensor%20reading%20%7D，这很好，但是有一些缺点：链接中的公式不易于阅读和更新，如果第三方服务出现问题，您的旧文档将停止工作...在TeXify中，即使卸载了该插件，您的旧文档仍将始终正常工作（因为从latex公式生成的所有图片都保留在存储库的tex目录中）。Yuchao Jiang在他的答案中建议使用Jupyter Notebook，这也很好，但是有些缺点：您无法直接在README.md文件中使用公式，需要在那里创建指向存储库中其他文件*.ipynb的链接，其中包含latex（MathJax）公式。文件*.ipynb格式为JSON，不方便维护（例如，当您忘记在正确位置放置逗号时，Gist不会显示*.ipynb文件中的行号详细错误...）。

这里是链接，其中一些我使用TeXify的repo，其文档是从README.tex.md文件生成的。

更新

今天2020.12.13，我意识到TeXify插件停止工作了 - 即使重新安装也是如此 :(

- Kamil Kiełczewski

---

@Royi 我不知道。 - Kamil Kiełczewski

很好，但是你如何处理/tex文件夹中大量未使用的垃圾SVG图像？ - Serge P.

@SergeP. 删除所有并推送吗？ - Kamil Kiełczewski

Answer 8

如果您想要在推送到GitHub时自动转换文件格式，请查看TeXify应用程序：

这是一个GitHub应用程序，它会检查您的推送中是否有扩展名为*.tex.md的文件，并将其TeX表达式渲染为SVG图像。

它是如何工作的（来自源代码库）：

每当您进行推送时，TeXify将运行并搜索您最后一次提交中的*.tex.md文件。对于每个这样的文件，它都会运行readme2tex，该程序将取出括在美元符号之间的LaTeX表达式，将其转换为纯SVG图像，然后将输出保存到.md扩展名文件中（这意味着名为README.tex.md的文件将被处理，输出将保存为README.md）。之后，输出文件和新的SVG图像将被提交并推回您的存储库。

- Tom Hale

---

这项工作是由@agurodriguez完成的，他在上面的评论中提到了它。 - icc97

@icc97 是的，但是 agurodriguez 没有提供答案（而且我可能永远不会注意到他的评论）。因为 Tom 创建了答案（在 agurodriguez 大约一年后），我注意到 TeXify 存在并且它允许我使用 TeXify 并基于此编写自己的 答案。所以这很好 :) - Kamil Kiełczewski

@KamilKiełczewski 这个回答没有任何问题，我只是想提一下 TeXify 是由一个 Stack Overflow 用户因为这个帖子而创建的，这很酷。 - icc97

我在我的readme中使用TeXify，但是不知何故，每当文本中有$...$时，渲染就会跳行。有什么线索吗？这是repo的链接：https://github.com/brunoconteleite/Spatial-Model-Solver - Bruno Conte Leite

Answer 9

我刚刚发布了xhub的新版本，这是一个浏览器扩展，可以在GitHub页面中渲染LaTeX（和其他内容）。

缺点：

• 您需要安装该扩展程序。

优点：

• 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

作为一个例子，看看这个GitHub README:

- Nico Schlömer

---

很酷，但是它不能将数学公式呈现给其他访问者（比如我），这正是 README 的重点... - Jthorpe

只对安装了该扩展程序的其他访客有效。 - Nico Schlömer

Answer 10

虽然 Markdown 支持 LaTeX 已经从2022年5月开始，但是随着2023年5月的更新，内联表达式更好地表示出来:

新的行内数学表达式分隔符语法 (2023年5月)

我们正在引入一种新方法，用于在 Markdown 中内联包含基于 LaTeX 的数学表达式。
除了现有的分隔符之外，我们现在支持使用美元符号和反引号作为 LaTeX 风格的数学语法分隔符（例如，$\sqrt{3}$）。
如果您编写的数学表达式包含与 Markdown 语法重叠的字符，则此新语法尤其有用。

要了解有关在 GitHub 上使用 Markdown 中的数学表达式的更多信息，请查看 GitHub 文档中的"编写数学表达式"。

- VonC