Integrating KaTeX into an Astro Template for LaTeX Math Rendering

1. Install Dependencies

Install the remark and rehype plugins that add math support to Markdown, along with KaTeX itself. remark-math parses math syntax in Markdown; rehype-katex renders the parsed nodes to KaTeX output at build time. Run the following in your project root:

# 使用 npm 或 pnpm 安装所需的插件和 KaTeX 库
pnpm add remark-math rehype-katex katex
# 如果使用 npm:
# npm install remark-math rehype-katex katex

This adds three packages: remark-math, rehype-katex, and katex.

2. Update the Astro Config

Wire both plugins into Astro's Markdown rendering pipeline. Open astro.config.mjs (or astro.config.ts) and make the following changes:

import { defineConfig } from 'astro/config';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  // ... 其他 Astro 配置 ...
  markdown: {
    // 添加 remark 和 rehype 插件以支持数学公式
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeKatex],
  },
  // ... 其他 Astro 配置 ...
});

With this config, Astro first runs remark-math to parse $...$ and $$...$$ delimiters into math nodes, then runs rehype-katex to render those nodes as HTML and MathML. If your project already has other remarkPlugins or rehypePlugins entries, append to those arrays rather than replacing them.

3. Load the KaTeX Stylesheet

The plugin configuration alone is not enough. Without KaTeX's CSS, rendered formulas will lack correct typography and fonts. Add the stylesheet link to the <head> of your main layout file (for example, src/layouts/Layout.astro):

---
import { Astro } from 'astro';
---
<html>
  <head>
    <!-- 其他元数据和样式 -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" />
  </head>
  <body>
    <slot />  <!-- 页面主要内容 -->
  </body>
</html>

If a CDN is not suitable, you can instead add import 'katex/dist/katex.min.css' in the frontmatter of your layout component to load the stylesheet from the local katex package. Either way, verify after building that katex.min.css is actually present in the page's <head>.

4. (Optional) Dark Mode Color Fix

If your blog supports dark mode or uses Tailwind CSS's typography plugin, the default KaTeX output may conflict with a dark background. Block-level formulas carry the .katex-display class, and their text color defaults to black, which becomes invisible against a dark surface. Add the following rule to your global stylesheet:

.prose .katex-display {
  color: inherit;  /* 继承父元素的文本颜色 */
}

This makes formula text inherit the surrounding text color, keeping formulas visible on dark backgrounds. Adjust the selector to match your site's CSS architecture. If you don't use dark mode or the Tailwind typography plugin, skip this step.

With those four steps complete, the plugins and styles are in place.

Writing LaTeX in Markdown

Inline formulas use single dollar signs: $E = mc^2$ renders as $E = mc^2$. Block formulas use double dollar signs, each on their own line:

在质能方程中，质量和能量的关系可以表示为：
$$
E = mc^2
$$

另一个示例是二次方程的求根公式：
$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Commands like \sum and \int work as expected. KaTeX supports nearly all common LaTeX math symbols and environments directly inside Astro Markdown.

Troubleshooting Notes

Formula renders as plain text: If $E = mc^2$ appears as-is on the page, remark-math is either not configured or the syntax is wrong. Confirm that remarkPlugins: [remarkMath] is present in astro.config.mjs. For inline formulas, avoid line breaks inside the delimiters; for block formulas, the opening and closing $$ must each be on their own line.
Rendered formula looks wrong: Incorrect typography, misaligned elements, or wrong colors usually indicate that katex.min.css is not loaded. Open browser DevTools and check the network panel or the element inspector to confirm the stylesheet is present and applied.
Formulas invisible in dark mode: A formula that disappears in dark mode is typically a color collision—formula text is black against a dark background. Setting .katex-display { color: inherit; } in your global CSS resolves this.
Build-time errors on complex formulas: A typo—unclosed bracket, misspelled command—in a LaTeX expression can cause the Astro build to fail, because remark-math errors on invalid syntax. Fix the formula syntax in the Markdown file to resolve the build failure.

Astro does not render LaTeX out of the box, but the remark/rehype plugin chain and KaTeX make the extension straightforward.