Github Pages采用的是Jekyll静态页面生成器,其kramdown引擎支持MathJax。MathJax功能丰富,但是体积庞大,渲染较慢。所以,我还是比较喜欢轻量级的KaTex

自定义layout

首先要往Github Pages添加一个主题,参考: https://help.github.com/en/github/working-with-github-pages/adding-a-theme-to-your-github-pages-site-using-jekyll。这个帮助文档中也介绍了如何定制主题。简单的说就是把主题的_layouts/default.html拷贝到当前仓库中(需要注意你的GithubPages是在哪个git分支的哪个目录中)。比如说你使用的主题是Minimal,那么其_layouts/default.html就在https://github.com/pages-themes/minimal/blob/master/_layouts/default.html。(额外参考https://github.com/pages-themes/minimal#layouts

关于Github Pages中KaTex的配置,主要参考的是Math support with KaTeX on Github Pages

    {% comment %} include katex >>>  {% endcomment %}

    <!-- katex -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.css" integrity="sha384-zB1R0rpPzHqg7Kpt0Aljp8JPLqbXI3bhnPWROx27a9N0Ll6ZP/+DiW/UqRcLbRjq" crossorigin="anonymous">

    <!-- The loading of KaTeX is deferred to speed up page rendering -->
    <script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.js" integrity="sha384-y23I5Q6l+B6vatafAwxRu/0oK/79VlbSz7Q9aiSZUvyWYIYsd+qj+o24G5ZU2zJz" crossorigin="anonymous"></script>

    <!-- To automatically render math in text elements, include the auto-render extension: -->
    <script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/contrib/auto-render.min.js" integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI" crossorigin="anonymous"
        onload="renderMathInElement(document.body);"></script>

    {% comment %} include katex <<< {% endcomment %}

    <script>
    // based on https://github.com/stevenkaras/stevenkaras.github.com/blob/master/_includes/js/katex.js

    document.addEventListener("DOMContentLoaded", function() {
        renderMathInElement(document.body, {'delimiters' : [
            {left: "$$", right: "$$", display: true},
            {left: "\\[", right: "\\]", display: true},
            {left: "$", right: "$", display: false},
            {left: "\\(", right: "\\)", display: false}
        ]});

        document.querySelectorAll("script[type='math/tex; mode=display']").forEach(function(el) {
            el.outerHTML = katex.renderToString(el.textContent.replace(/%.*/g, ''), { displayMode: true });
        });
    });
    </script>

上面的katex部分的内容参考自:https://katex.org/docs/browser.html

添加页面列表

根据Jekyll的说明,添加一个list.md文件到根目录,内容如下:

<ul>
  {% for post in site.posts %}
    <li>
      <a href="{{ post.url }}">{{ post.title }}</a>
    </li>
  {% endfor %}
</ul>

访问https://username.github.io/list就可以查看所有posts。

测试页面

参考https://help.github.com/en/github/working-with-github-pages/adding-content-to-your-github-pages-site-using-jekyll,在根目录下创建一个_posts子目录,里面放一个2019-11-08-test.md(命名要求来自Jekyll)。内容如下:

---
layout: post
title:  "Welcome to Jekyll!"
math: true
---

# Test

$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$

结果通过https://username.github.io/2019/11/08/test.html访问,老是显示404页面,搞得整个人都没有脾气了……

小结

本来还想着在本地使用jekyll来调试一下,看问题出在何处。可是基于ruby的jekyll安装麻烦(不管是在windows还是在mac),需要编译扩展。Ruby的gem机制也难用,默认没有sudo权限竟然不知道安装到用户目录,而是需要用户指定gem install --user-install jekyll。安装完以后执行jekyll也很慢。看来jekyll能在https://www.staticgen.com/名列三甲,纯粹是因为它是Github默认支持的。

还是使用其他更简单的生成器,基本Github不能自动帮你生成页面……

其他参考

2021-11-23 更新

根据How to support latex in GitHub-pages?里面的这个回复

先在 _config.yml中把markdown引擎改为kramdown,再设置其公式渲染引擎为katex:

theme: jekyll-theme-minimal
# https://stackoverflow.com/a/57370526
markdown: kramdown
kramdown:
    math_engine: katex

假设依然使用minimal主题,查看https://github.com/pages-themes/minimal/blob/master/_layouts/default.html,可知此主题会默认包含head-custom.html

 {% include head-custom.html %}

创建一个_includes/head-custom.html,内容来自https://katex.org/docs/autorender.html

 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.css" integrity="sha384-R4558gYOUz8mP9YWpZJjofhk+zx0AS11p36HnD2ZKj/6JR5z27gSSULCNHIRReVs" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.js" integrity="sha384-z1fJDqw8ZApjGO3/unPWUPsIymfsJmyrDVWC8Tv/a1HeOtGmkwNd/7xUS0Xcnvsx" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/contrib/auto-render.min.js" integrity="sha384-+XBljXPPiv+OzfbB3cVmLHf4hdUFHlWNZN5spNQ7rmHTXpd7WvJum6fIACpNNfIR" crossorigin="anonymous"
    onload="renderMathInElement(document.body);"></script>

这样就可以使用以下方式来插入公式了:

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

比如$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$

也可以修改默认的公式标签识别方式,增加$...$为行内公式标签:

<script>
    document.addEventListener("DOMContentLoaded", function() {
        renderMathInElement(document.body, {
          // customised options
          // • auto-render specific keys, e.g.:
          delimiters: [
              {left: '$$', right: '$$', display: true},
              {left: '$', right: '$', display: false},
              {left: '\\(', right: '\\)', display: false},
              {left: '\\[', right: '\\]', display: true}
          ],
          // • rendering keys, e.g.:
          throwOnError : false
        });
    });
</script>

(更新完)