Github 上 README.md 中的 Latex 渲染

Question

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

Answer 1

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

- <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降价在下一个方式：

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

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

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

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

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

更多信息在这里。

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

Answer 3

我的诀窍是使用 Jupyter Notebook。

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

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

Answer 4

自述文件

我一直在编写一个脚本，该脚本可以自动将 LaTeX 排版的大部分问题自动化到 Github 风格的降价中： https : //github.com/leegao/readme2tex

为 Github 渲染 LaTeX 有一些挑战。 首先，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 5

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

Answer 6

我测试的人提出了一些解决方案，我想推荐TeXify创建并通过评论提出agurodriguez并进一步描述汤姆·黑尔-我想发展自己的答案，并给予一定的原因，这是很好的解决方案：

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

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

更新

今天 2020.12.13 我意识到 TeXify 插件停止工作 - 即使在重新安装后:(

Answer 7

对于推送到 GitHub 时的自动转换，请查看TeXify应用程序：

GitHub 应用程序，它会在您的推送中查找扩展名为 *.tex.md 的文件，并将其 TeX 表达式呈现为 SVG 图像

它是如何工作的（来自源存储库）：

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

Answer 8

我刚刚发布了一个新版本的xdoc ，这是一个浏览器扩展，可以在 GitHub 页面中呈现 LaTeX（和其他东西）。 您可以从

https://chrome.google.com/webstore/detail/xdoc/anidddebgkllnnnnjfkmjcaallemhjee

然后，每个包含数学的 GitHub 页面，例如，

This is markdown with some display math
```math
a^b + b^2 = c^2
```
and some inline math, $`e^{i\pi} + 1 = 0`$.

将如此呈现。 参见，例如，这个 GitHub README ：

就像GitLab 的原生数学支持一样，它是基于KaTeX 的。

Answer 9

您可以获得持续集成服务（例如Travis CI ）来呈现 LaTeX 并将结果提交到 github。 CI 将在每次新提交后部署一个“云”工作者。 工作人员将您的文档编译为 pdf 并使用 ImageMagick 将其转换为图像或使用 PanDoc 尝试 LaTeX->HTML 转换，其中成功可能因您的文档而异。 Worker 然后将图像或 html 提交到您的存储库，从那里它可以在您的自述文件中显示。

下面粘贴了构建 PDF、将其转换为 PNG 并将其提交到存储库中的静态位置的示例 TravisCi 配置。 您需要添加一行来获取 pdfconverts PDF to an image

sudo: required
dist: trusty
os: linux
language: generic
services: docker
env:
  global:
  - GIT_NAME: Travis CI
  - GIT_EMAIL: builds@travis-ci.org
  - TRAVIS_REPO_SLUG: your-github-username/your-repo
  - GIT_BRANCH: master
# I recommend storing your GitHub Access token as a secret key in a Travis CI environment variable, for example $GH_TOKEN.
  - secure: ${GH_TOKEN}
script:
- wget https://raw.githubusercontent.com/blang/latex-docker/master/latexdockercmd.sh
- chmod +x latexdockercmd.sh
- "./latexdockercmd.sh latexmk -cd -f -interaction=batchmode -pdf yourdocument.tex -outdir=$TRAVIS_BUILD_DIR/"
- cd $TRAVIS_BUILD_DIR
- convert -density 300 -quality 90 yourdocument.pdf yourdocument.png
- git checkout --orphan $TRAVIS_BRANCH-pdf
- git rm -rf .
- git add -f yourdoc*.png
- git -c user.name='travis' -c user.email='travis' commit -m "updated PDF"
# note we are again using GitHub access key stored in the CI environment variable
- git push -q -f https://your-github-username:$GH_TOKEN@github.com/$TRAVIS_REPO_SLUG $TRAVIS_BRANCH-pdf
notifications:
  email: false

这个 Travis Ci 配置启动一个 Ubuntu 工作器，下载一个 Latex docker 图像，将您的文档编译为 pdf 并将其提交到一个名为 branchanme-pdf 的分支。

有关更多示例，请参阅此 github 存储库及其随附的 sx 讨论、 PanDoc 示例、 https: //dfm.io/posts/travis-latex/以及Medium 上的这篇文章。

Answer 10

如果您在使用https://www.codecogs.com/latex/eqneditor.php 时遇到问题，我发现https://alexanderrodin.com/github-latex-markdown/对我有用。 它会生成您需要的 Markdown 代码，因此您只需将其剪切并粘贴到 README.md 文档中即可。

Answer 11

您还可以查看我的工具latexMarkdown2Markdown ，它将 LaTeX 转换为 SVG 并生成带有章节编号的目录。

Answer 12

我一直在环顾四周，发现另一个问题中的这个答案最适合我。 即使用 githubcontent 数学渲染器，例如显示：

使用此链接注意乳胶需要进行 url 编码，否则对我来说效果很好。

Answer 13

编辑：正如germanium 所指出的，它不适用于README.md，但适用于其他git 页面，尽管没有可用的解释。 我的快速解决方案是这样的

第 1 步。将乳胶添加到您的.md文件中

$$x=\sqrt{2}$$

注意：数学方程必须在 $$...$$ 或\\\\(... \\\\) 。

步骤 2. 将以下内容添加到您的scripts.html或主题文件中（将此代码附加到末尾）

<script type="text/javascript" async

src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML">

完毕！。 看到你的方程。 通过加载页面。

Answer 14

您可以使用降价，例如

![equ](https://latex.codecogs.com/gif.latex?log(y)=\beta_0&space;+&space;\beta_1&space;x&space;+&space;u)

代码可以在这里输入： https : //www.codecogs.com/latex/eqneditor.php 。