向 Astro 博客添加 KaTeX 支持
前言
最近在写博客文章中有需求在其中添加数学公式，而 Astro 默认是不支持公式渲染的。不过提到数学公式渲染，首先就会想到 。KaTeX 是一个轻量级的数学公式渲染引擎，由可汗学院开发，它可以在浏览器中快速渲染数学公式，同时渲染出来的公式看起来也很漂亮。所以我决定在我的博客中使用 KaTeX 来渲染数学公式。
原理
在 Astro 官方文档中有提到 Astro 渲染 Markdown 是使用 remark 和 rehype 来处理的。所以我们可以使用 remark 插件来添加 KaTeX 支持。至于原理，简单来说就是在 Markdown 中使用特定的语法 $$C_L$$ 来标记数学公式，然后在渲染成 HTML 时将这些语法转换为 HTML 标签，最后让 KaTeX 的 CSS 来渲染这些标签。
实现
简单搜索了一下，remark 有一个官方的插件 remark-math 可以用来添加数学公式支持，所以我们可以直接使用这个插件来添加 KaTeX 支持（它也同样支持 MathJax）。插件的仓库在这里：https://github.com/remarkjs/remark-math
安装 remark-math 和 rehype-katex 之后，我们需要在 astro.config.mjs 中添加配置来启用这两个插件。在 astro.config.mjs 中添加以下配置：
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';
import tailwind from '@astrojs/tailwind';
+ import remarkMath from 'remark-math';
+ import rehypeKatex from 'rehype-katex';
import vue from "@astrojs/vue";
// https://astro.build/config
export default defineConfig({
integrations: [mdx(), sitemap(), vue(), tailwind({
applyBaseStyles: false
})],
markdown: {
+ remarkPlugins: [remarkMath],
+ rehypePlugins: [rehypeKatex],
},
});
根据 remark-math 文档，我们还需要在渲染的 HTML 的 <head> 中添加 KaTeX 的 CSS 文件，这样才能正常渲染公式（这里推荐从站外加载，当然你也可以直接通过 npm 安装 KaTeX 并引入，不过这样会增加打包文件的大小。仅仅在 CDN 无法连接的情况下，你才需要这么做）。
<!-- Get the latest one from: https://katex.org/docs/browser -->
<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" rel="stylesheet">
测试行内渲染
测试单行渲染效果：
总结
这次配置 的过程还是意外地比较简单的，只需要安装两个插件，然后在 astro.config.mjs 中添加配置即可。不过需要注意的是，KaTeX 的 CSS 文件需要在 <head> 中引入，否则无法正常渲染公式。不过这个问题在官方文档中也有提到，仔细阅读文档就能看到。
在浏览的时候看到一篇文章提到如果非全局加载 CSS 的情况下可能会出现渲染问题，这个是必然现象。如果你开启了全站 SPA，在从不带有 CSS 的页面跳转到带有 CSS 的页面时，此时 KaTeX 的 CSS 可能没有成功加载，导致公式无法正常渲染。建议在全站 SPA 的情况下，将 KaTeX 的 CSS 文件放在全局的 head 中引入。或者关闭全站 SPA，这样每个页面都会重新加载 head。