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不能自动帮你生成页面……
其他参考
- KaTeX and MathJax Comparison Demo
- How to support latex in github-pages?
- Comment out an include statement inside an HTML file using Jekyll
- https://help.github.com/en/github/working-with-github-pages 2016
- About GitHub Pages and Jekyll
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>
(更新完)