logo标签列表

如何在GitHub Pages上支持LaTeX？

jekyllgithub-pages
82

我使用jekyll来撰写文章并在GitHub Pages上展示。我的源文件是用markdown编写的。

我如何在markdown文件中插入公式？

我不想将公式保存为图像并在markdown文件中加载图像。我实际上希望直接在markdown文件中编写latex公式。

1
从未尝试过，但似乎可行 http://gastonsanchez.com/blog/opinion/2014/02/16/Mathjax-with-jekyll.html - DomDom
2
这个简单的解决方案对我有用：http://zjuwhw.github.io/2017/06/04/MathJax.html - psyguy
我正在使用带有Sphinx的.rst文件（而不是markdown）。这非常简单明了。如果可以选择，我建议使用它们。这个项目就是一个例子。还有一些Sphinx扩展可以读取markdown，但我没有尝试过。 - joel
8个回答
62

由于在线资源有所变化，这里提供一份关于如何在GitHub Pages上支持LateX的更新。

请注意，最接近原生支持Latex渲染且无需导出为图片的方法是使用MathJax。

事实上，Jekyllrb文档推荐使用MathJax进行数学支持，并使用Kramdown将其从LaTeX转换为PNG。更多细节可参考Kramdown文档。

选项1：使用MathURL编写方程式并嵌入其中。

您可以使用MathURL编写方程式，然后生成一个永久指向该方程式的URL，并在<iframe>标签中显示它。但是，如果MathURL离线，则此方法将无法使用。

选项2：实现jsMath。

如果您正确设置了它，jsMath将允许几乎类似于LateX的语法，并且将在您的博客中得到支持。有广泛的文档。

选项3：Mathjax（在我看来迄今为止最容易）

许多网站提到Mathjax被认为是jsMath的继承者，并且在使用Jekyll时更容易实现。 MathJax也被mathematics.stackexchange.com使用！

  • 步骤1：在您想要显示数学公式的网站上加载脚本。（通常在头部完成）

  • 可选：检查_config.yml中的markdown解析器。redcarpet或kramdown建议在此示例中使用。某些解析器（如discount）会干扰语法，但我下面有一个解决方案。

  • 步骤2：编写您的方程式。

引用Gaston Sanchez的教程：

MathJax的行为与LaTeX不完全相同。默认情况下，tex2jax预处理器定义了LaTeX数学定界符，即用于内联数学的\(...\)和用于显示方程的\[...\]。它还定义了用于显示方程的TeX定界符$$...$$，但没有定义用于内联数学的$...$。

阅读文档以获取更多详细信息的语法。

  • 注意: 使用raw liquid标签确保Markdown解析器不会干扰MathJax语法。
  • 虽然您可以转义反斜杠（例如\\[ \frac{1}{n^{2}} \\]）以确保它们被正确解析，正如Chistopher Poole的教程所描述的那样，但这并不总是直观且看起来很复杂。更简单的解决方案是使用原始液体标记确保Markdown处理器忽略文本并直接输出为静态html。这可以通过{% raw %}和{% endraw %}完成。

以下是代码示例：

 {% raw %}
  $$a^2 + b^2 = c^2$$ --> note that all equations between these tags will not need escaping! 
 {% endraw %}

最后，请确保字体支持显示LateX，因为有些字体存在问题，例如字体大小太小。或者，您可以参考latex StackExchange姐妹站点中讨论的其他方法，如Google Charts和MathML。
MathJax 对我来说完美地运作了。http://docs.mathjax.org/en/latest/start.html 上的页面有一个很好的示例。 - MxNx
这是一篇非常好的博客文章，介绍如何在jekyll中使用mathjax。 - glS
现在只需在帖子布局中添加mathjax脚本标签即可。文档中已经非常清楚了：https://jekyllrb.com/docs/extras/#math-support - user2516837
4
@user2516837，这个链接似乎不存在了。 - agent18
47

如果您在GitHub Pages中使用了Jekyll，您可以添加：

  <script type="text/x-mathjax-config">
    MathJax.Hub.Config({
      tex2jax: {
        skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
        inlineMath: [['$','$']]
      }
    });
  </script>
  <script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>

在文件_includes/head.html中添加以下代码，你的GitHub Pages网站将支持MathJax。

1
使用Jekyll；这个简单的解决方案效果很好！示例（1）：$h_\theta(x) = \Large\frac{1}{1 + \mathcal{e}^{(-\theta^\top x)}}$；示例（2）：$a^2 + b^2 = c^2$；示例（3）：$\sum_{i=1}^m y^{(i)}$ - Victoria Stuart
3
根据文档http://docs.mathjax.org/en/v2.7-latest/start.html#using-a-content-delivery-network-cdn，"src"链接应替换为以下之一："src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-MML-AM_CHTML""或"src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-MML-AM_CHTML"。 - Plo_Koon
@Plo_Koon 你怎么将这个转换为MathJax 3？ - user760900
1
现在文件必须是_includes/head-custom.html。 - asmaier
截至2023年3月，这对我有用，将脚本放在head.html中。 - lafinur
18

目前最简单的方法是使用KaTeX的自动渲染扩展功能。

只需将以下内容添加到<head>中：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.2/dist/katex.min.css" integrity="sha384-yFRtMMDnQtDRO8rLpMIKrtPCD5jdktao2TV19YiZYWMDkUR5GQZR/NOVTdquEx1j" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.10.2/dist/katex.min.js" integrity="sha384-9Nhn55MVVN0/4OFx7EE5kpFBPsEMZxKTCnA+4fqDmg12eCTqGi6+BB2LjY8brQxJ" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.10.2/dist/contrib/auto-render.min.js" integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI" crossorigin="anonymous" onload="renderMathInElement(document.body);"></script>

请注意，这假设以下分隔符出现在您的HTML中：

$$\LaTeX code$$   (for display)
\\[\LaTeX code\\] (also for display)
\\(\LaTeX code\\) (for inline)

请注意，如果使用Jekyll，您需要在_config.yml文件中添加以下内容:

markdown: kramdown
kramdown:
    math_engine: katex

警告：不要使用math_engine: mathjax。它会自动删除LaTeX分隔符，导致出现问题。

我无法给这个点赞次数足够多，太简单了。而且它工作得非常好！非常感谢。 - Max Smith
很遗憾，此答案已经过时，请参阅我的更新答案：https://dev59.com/kl8d5IYBdhLWcg3w615T#72383929。 - asmaier
@asmaier，哪一部分已经过时了？GH Pages不再干扰LaTeX定界符，因此不再需要指定math_engine吗？ - daviewales
3

不幸的是，这里大部分的回答在今天已经过时了。Github使用kramdown来渲染你的markdown文件。令人烦恼的是kramdown定义数学内容的方式与其他markdown变体不同。在kramdown中，行内数学公式使用$$作为定界符，例如：text $$ E = mc^2 $$ text，而显示数学公式也使用$$定界符，但必须与文本之间用空白行分隔。

text

$$\begin{aligned}
E = mc^2
\end{aligned}$$

text

Kramdown会将行内公式渲染为\( E = mc^2 \)，将块级公式渲染为：
\[\begin{aligned}
E = mc^2
\end{aligned}\]

在你的输出HTML中使用这些标记符。这也是MathJax默认使用的定界符。因此，要为GitHub Pages配置MathJax 3，只需添加以下内容：

<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

将内容添加到文件_includes/head-custom.html中。您无需创建或修改_config.yml文件。
我建议您使用MathJax 3而不是KaTeX，因为MathJax 3的速度与KaTeX相比不再慢很多（请参见https://www.intmath.com/cg5/katex-mathjax-comparison.php），并且支持更多功能（例如，KaTex无法处理\label和\eqref（请参见https://github.com/KaTeX/KaTeX/issues/2003））。
如果您仍然想使用https://katex.org/docs/autorender.html，则必须添加：
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.6/dist/katex.min.css" integrity="sha384-ZPe7yZ91iWxYumsBEOn7ieg8q/o+qh/hQpSaPow8T6BwALcXSCS6C6fSRPIAnTQs" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.6/dist/katex.min.js" integrity="sha384-ljao5I1l+8KYFXG7LNEA7DyaFvuvSCmedUf6Y6JI7LJqiu8q5dEivP2nDdFH31V4" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.6/dist/contrib/auto-render.min.js" integrity="sha384-+XBljXPPiv+OzfbB3cVmLHf4hdUFHlWNZN5spNQ7rmHTXpd7WvJum6fIACpNNfIR" crossorigin="anonymous"
    onload="renderMathInElement(document.body);"></script>

将内容添加到文件_includes/head-custom.html中。您不需要创建或修改_config.yml文件。

注意：我尝试使用GitHub页面的默认渲染器之外的GitHub风格的Markdown渲染器，通过在_config.yml文件中设置markdown: GFM。这将为您提供其他功能，例如自动链接（请参见https://github.community/t/github-pages-autolinks-fail/129713/4）以及更常见的行内数学公式分隔符$和显示数学公式分隔符$$（https://github.blog/2022-05-19-math-support-in-markdown/），因为它受到https://pandoc.org/的支持。然而，来自GitHub的GFM markdown渲染器在处理数学部分时仍然存在许多问题，使其无法使用（https://nschloe.github.io/2022/05/20/math-on-github.html）。

这是最好的解决方案，但对于那些不知道如何使用jekyll但仍想使用自定义模板的人来说，我很难让它起作用，因为我的模板没有包括“head-custom.html”，而是使用了“head/custom.html”。所以，我必须在_include/head/custom.html中包含这一行。对于其他遇到同样问题的人，您可以查看原始模板存储库中_layouts/default.html中包含的文件，以确定要添加此html文件的位置。 - Ashwin Rajesh
我采纳了@AshwinRajesh的建议，查看了_layouts/default.html文件，并发现在我的文件系统中相关的文件是_includes/head.html。在<head></head>之间添加了该行代码后，渲染正常工作。 - Life is Good
谢谢，它对于像数学公式 $$xxxxx$$ 这样的内容效果非常好，但是它无法渲染 $yyyyyy$ 这样的数学公式，请问我需要在 head-custom.html 中添加其他内容吗？ - Jimmy Zhao
谢谢，它对于像数学公式 $$xxxxx$$ 这样的内容效果非常好，但是它无法渲染 $yyyyyy$ 这样的数学公式，我需要在 head-custom.html 中添加其他内容吗？ - undefined
我在_includes文件夹中只有一个custom-footer.html文件，我该怎么办？ - undefined
2

前一段时间，我创建了xhub，这是一个浏览器扩展程序，可以让你在github页面中使用数学公式。

缺点：

  • 你需要安装这个扩展程序。

优点：

  • No need to set up any workflow.
  • Just edit your markdown as usual and use 
    Display math:
```math
e^{i\pi} + 1 = 0
```
and inline math $`a^2 + b^2 = c^2`$.
    (Syntax just like on GitLab.)
  • Works well on light and dark background.
  • You can even copy-and-paste the math!
也许值得一看。 enter image description here
1
我希望这是对daviewales答案的评论，但不幸的是我的声誉不够。我理解那个答案是将三行代码复制到文件<your_repo>.github.io\_site\<postname>\index.html中。然而，每次编辑相应的<postname>.md时，该文件似乎会得到更新。是否有更优雅的方法始终自动添加这些代码行到html文件中，而无需每次手动编辑它以检查方程式？
编辑： 我认为这是上述问题的一个解决方案：
对我有效的是基于PeaShooter的回答。我在_posts文件夹中创建了一个名为_includes的文件夹，并在其中填充了一个名为head.html的文件，其中包含了PeaShooter答案中的代码。然后，在YAML前置元数据下的帖子顶部行（即第二个---行以下），我放置了代码{% include_relative _includes/head.html %} 请注意，将_includes文件夹放在基础文件夹<your_repo>.github.io中是不重要的，而是应该放在_posts文件夹中。将_includes放在基础文件夹中会自动生成方程式，但会破坏网站其余部分的格式。
没错。你不应该编辑生成的HTML文件！你还应该查看_layouts文件夹，其中包含默认页面模板。我只是在_includes/head.html中包含了KaTeX代码，这些代码会被_layouts中的默认模板捕获。 - daviewales
0

一些答案可能有点复杂或过时，所以这里提供一个最近对我很有效的解决方案。您可以使用布局来解决问题。

在您发布的文件夹（例如docs/）中创建一个_layouts文件夹。

创建default.html。这将是所有页面的布局。如果您刚开始创建页面，可以将其用作default.html文件的模板：

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
  </head>
  <body>
    {{ content }}
  </body>
</html>

然后在</html>之前添加此脚本：

<script
  src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
  type="text/javascript">
</script>

我遇到了一个问题，我正在使用minima主题。因此，如果我应用上面的更改，我的帖子中就会失去我的主题。我去了github仓库，复制了他们在default.html中所拥有的内容，并在</html>之前添加了上面的脚本，它起作用了！

我在这里找到了答案here。

0

目前我认为最好的方法是使用MathJax后端（它是kramdown的一部分，即可在GitHub Pages上使用），然后在前端使用KaTeX进行渲染。 KaTeX比MathJax更轻量级和更快，这使得它更适合用于博客主题。

我正在使用这种技术来成功地制作我的Jekyll主题Hydejack。随意在您自己的网站上使用它，只需执行以下操作：

在config.yml中，将数学引擎设置为mathjax：

kramdown:
  math_engine: mathjax

将KaTeX添加到您的网站中，确保以下代码在加载后某个时间运行。

const mathBlocks = document.querySelectorAll('script[type^="math/tex"]');
Array.from(mathBlocks).forEach((el) => {
  const tex = el.textContent.replace("% <![CDATA[", "").replace("%]]>", "");
  el.outerHTML = window.katex.renderToString(tex, {
    displayMode: el.type === "math/tex; mode=display",
  });
});

我正在使用的实际代码稍微复杂一些。你可以在 GitHub 上查看它。

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接