feat: build-time math rendering with KaTeX via Satteri plugin

Author: Kingpython123

astro.config.mjs

@@ -1,17 +1,34 @@
 // @ts-check
 
+import { satteri } from '@astrojs/markdown-satteri';
 import mdx from '@astrojs/mdx';
 import sitemap from '@astrojs/sitemap';
 import tailwindcss from '@tailwindcss/vite';
 import { defineConfig, fontProviders } from 'astro/config';
 
+import { satteriKatex } from './src/plugins/satteri-katex.mjs';
+
 // https://astro.build/config
 export default defineConfig({
 	// 仓库名匹配 <username>.github.io，因此不需要配置 base
 	site: 'https://kingpython123.github.io',
 
 	integrations: [mdx(), sitemap()],
 
+	markdown: {
+		// Astro 7 的默认 Markdown 管线是 Sätteri（不是 remark/rehype），
+		// 所以数学公式走它的 math 解析特性 + 自写的 KaTeX 渲染插件，
+		// 不需要换成 unified，也就不用引入整套 remark 生态。
+		// mdx() 默认继承这份配置，.mdx 文件同样生效。
+		processor: satteri({
+			features: {
+				// $$...$$ 行间公式，$...$ 行内公式
+				math: { singleDollarTextMath: true },
+			},
+			mdastPlugins: [satteriKatex()],
+		}),
+	},
+
 	fonts: [
 		{
 			// Astro 在构建时下载并自托管字体文件，运行时不请求 Google

package-lock.json

@@ -12,11 +12,13 @@
     "astro": "astro"
   },
   "dependencies": {
+    "@astrojs/markdown-satteri": "0.3.4",
     "@astrojs/mdx": "^7.0.3",
     "@astrojs/rss": "^4.0.19",
     "@astrojs/sitemap": "^3.7.3",
     "@tailwindcss/vite": "^4.3.3",
     "astro": "^7.1.3",
+    "katex": "0.18.1",
     "sharp": "^0.35.0",
     "tailwindcss": "^4.3.3"
   }

package.json

@@ -1,4 +1,8 @@
 ---
+// KaTeX 的样式表放在 global.css 之前导入，这样我们自己的 .prose 规则
+// 在同等优先级下能覆盖它。字体文件由 Vite 解析 url() 后一起打包自托管，
+// 浏览器只在页面真的出现公式字形时才会去下载。
+import 'katex/dist/katex.min.css';
 // Import the global.css file here so that it is included on
 // all pages through the use of the <BaseHead /> component.
 import '../styles/global.css';

src/components/BaseHead.astro

@@ -1,4 +1,3 @@
 // 全站共用的常量。SITE_TITLE 会同时出现在页头、页脚、RSS 和浏览器标签上。
-// TODO: 换成你的真名或惯用署名
-export const SITE_TITLE = 'Kingpython123';
-export const SITE_DESCRIPTION = '机器学习与系统方向的技术学习笔记。';
+export const SITE_TITLE = 'sup';
+export const SITE_DESCRIPTION = 'sup的技术学习笔记。';

src/consts.ts

@@ -0,0 +1,61 @@
+---
+title: '公式渲染测试'
+description: '验证 KaTeX 在构建时的渲染效果，确认无误后可以删掉这篇。'
+pubDate: '2026-07-25'
+---
+
+这是一篇临时的验证文章，确认公式管线正常后可以直接删除。
+
+## 行内公式
+
+设注意力头数为 $h$，模型维度为 $d_{\text{model}}$，则每个头的维度是 $d_k = d_{\text{model}} / h$。当 $h = 8$、$d_{\text{model}} = 512$ 时 $d_k = 64$。
+
+行内公式不应该影响行高，这一段里混着 $\alpha$、$\sum_{i=1}^{n} x_i$ 和 $\mathcal{O}(n \log n)$，行距应当保持均匀。
+
+## 行间公式
+
+缩放点积注意力：
+
+$$
+\text{Attention}(Q, K, V) = \text{softmax}\left(\frac{QK^\top}{\sqrt{d_k}}\right) V
+$$
+
+多行对齐环境：
+
+$$
+\begin{aligned}
+\nabla_\theta \mathcal{L}(\theta) &= \nabla_\theta \left[ -\frac{1}{N} \sum_{i=1}^{N} \log p_\theta(y_i \mid x_i) \right] \\
+&= -\frac{1}{N} \sum_{i=1}^{N} \nabla_\theta \log p_\theta(y_i \mid x_i)
+\end{aligned}
+$$
+
+矩阵和分段函数：
+
+$$
+W = \begin{bmatrix} w_{11} & \cdots & w_{1n} \\ \vdots & \ddots & \vdots \\ w_{m1} & \cdots & w_{mn} \end{bmatrix}
+\qquad
+\text{ReLU}(x) = \begin{cases} x & x > 0 \\ 0 & x \le 0 \end{cases}
+$$
+
+一条很长的公式，用来检查窄屏下是否横向滚动而不是撑破版面：
+
+$$
+p(x_1, \dots, x_T) = \prod_{t=1}^{T} p(x_t \mid x_{<t}) = \prod_{t=1}^{T} \frac{\exp(z_{t, x_t})}{\sum_{v \in \mathcal{V}} \exp(z_{t, v})} \quad \text{where} \quad z_t = W_o \, \text{LayerNorm}(h_t) + b_o
+$$
+
+## 与代码块共存
+
+公式和代码块的字体、字号应当各自独立：
+
+```python
+d_k = d_model // n_heads
+scores = (q @ k.transpose(-2, -1)) / math.sqrt(d_k)
+```
+
+## 错误降级
+
+下面这条公式故意写错（`\frac` 缺参数），应当降级成带颜色的等宽原文，并在构建日志里出现一条 warning，但构建仍然成功：
+
+$$
+\frac{1}
+$$

src/content/blog/math-test.md

@@ -0,0 +1,62 @@
+import katex from 'katex';
+
+/**
+ * 把 Sätteri 解析出的 math / inlineMath 节点在构建时渲染成 KaTeX 的 HTML。
+ *
+ * Sätteri 的 math 特性只负责「解析」，把 $...$ 和 $$...$$ 变成 AST 节点，
+ * 渲染需要自己接。这里返回 { raw, mdxExpressions: false }：Sätteri 文档指明
+ * 注入 KaTeX 这类含花括号的生成 HTML 时必须关掉 mdxExpressions，
+ * 否则在 .mdx 文件里 {} 会被当成 JS 表达式求值。
+ *
+ * 公式在构建时就变成静态 HTML + MathML，浏览器端零 JS。
+ *
+ * @param {import('katex').KatexOptions} [userOptions]
+ */
+export function satteriKatex(userOptions = {}) {
+	// 传工厂而非定义对象，这样每篇文档拿到独立的插件实例，
+	// 文档内用 \gdef 定义的宏不会泄漏到下一篇。
+	return () => {
+		/** @param {{ value?: string }} node */
+		const render = (node, ctx, displayMode) => {
+			const source = node.value ?? '';
+
+			try {
+				const html = katex.renderToString(source, {
+					...userOptions,
+					displayMode,
+					// 出错时抛出，由下面接住并降级，而不是把红色报错直接印在页面上
+					throwOnError: true,
+					// 同时输出 HTML 和 MathML，屏幕阅读器能正确朗读公式
+					output: 'htmlAndMathml',
+					// 迁移过来的笔记里难免有非标准写法，别为此刷屏
+					strict: 'ignore',
+				});
+				return { raw: html, mdxExpressions: false };
+			} catch (error) {
+				// 不让一条写错的公式炸掉整个构建，降级成等宽原文。
+				// 注意：实测 Astro 7.1.3 不会把 Sätteri 的 diagnostics 打到构建日志里，
+				// 所以下面这条 report 目前只是留给未来（或自行调用 Sätteri 时）用的；
+				// 真正能看见的信号是页面上那段带底色的 .math-error 原文。
+				ctx.report({
+					message: `KaTeX 渲染失败：${error instanceof Error ? error.message : String(error)}`,
+					node,
+					severity: 'warning',
+				});
+				const escaped = source
+					.replace(/&/g, '&')
+					.replace(/</g, '&lt;')
+					.replace(/>/g, '&gt;');
+				return {
+					raw: `<code class="math-error" title="KaTeX 渲染失败">${escaped}</code>`,
+					mdxExpressions: false,
+				};
+			}
+		};
+
+		return {
+			name: 'satteri-katex',
+			math: (node, ctx) => render(node, ctx, true),
+			inlineMath: (node, ctx) => render(node, ctx, false),
+		};
+	};
+}

src/plugins/satteri-katex.mjs

@@ -220,6 +220,25 @@
 		border-block-start: 1px solid var(--color-rule);
 	}
 
+	/* 数学公式：KaTeX 默认按 1.21em 放大，衬线正文里显得过大，压回接近正文字号 */
+	.prose .katex {
+		font-size: 1.06em;
+	}
+
+	/* 长公式在窄屏上横向滚动，而不是撑破版面 */
+	.prose .katex-display {
+		margin-block: 1.5em;
+		padding-block: 0.25em;
+		overflow-x: auto;
+		overflow-y: hidden;
+	}
+
+	/* 写错的公式降级成原文，用颜色标出来好排查 */
+	.prose .math-error {
+		color: #a3324b;
+		background-color: #fdf0f2;
+	}
+
 	.prose sup a {
 		text-decoration: none;
 	}