KaTeX integration issues in Astro Starlight; MathJax workaround feels brittle

[YutaroIshihama]

What version of starlight are you using?

0.36.0

What is your idea?

I would love to see native support for KaTeX in Astro Starlight—built-in and officially maintained, without relying on plugins or manual rehype configuration. Ideally, math rendering should work out of the box with minimal setup, just like Markdown does. This would make Starlight a more robust choice for technical and educational documentation.

Why is this feature necessary?

KaTeX works well in pure Astro projects using rehype-katex, but in Starlight, the same setup fails to render properly. Documentation and messaging around Starlight often imply that KaTeX is natively supported, but in practice, it doesn’t work out of the box. This mismatch creates confusion and leads users down a path of trial-and-error.
I’ve had to abandon KaTeX and switch to MathJax, which introduces complexity: manual script injection, fragile CSS overrides, and layout inconsistencies. These workarounds feel brittle and undermine reproducibility—especially for math-heavy documentation workflows.
As someone building reproducible, keyboard-friendly documentation for educational use, I need math rendering that’s declarative, reliable, and frictionless. Native KaTeX support would reduce onboarding friction, improve clarity, and align with Starlight’s mission of beautiful, scalable docs.

Do you have examples of this feature in other projects?

• Pure Astro: KaTeX works seamlessly with rehype-katex in vanilla Astro setups. The rendering is fast, lightweight, and requires no CSS hacks.
• Docusaurus: Offers built-in KaTeX support via plugin configuration, with predictable rendering and minimal setup.
• HonKit (GitBook CLI fork): Supports KaTeX natively for math-heavy books, making it a go-to for reproducible technical writing.
  These examples show that KaTeX can be integrated cleanly and declaratively. I believe Starlight could offer the same elegance—without forcing users into fragile MathJax workarounds.
• GitHub Pages + Jekyll/Markdown: Many technical documentation sites hosted on GitHub Pages use KaTeX via simple Markdown + KaTeX injection, often with minimal configuration. The reproducibility and clarity of math rendering in these setups is a strong reference point.

Participation

• I am willing to submit a pull request for this feature.

[HiDeoo]

Thanks for the feedback.

Katex support in Starlight is available using a Starlight plugin which bundles in a simple package all the necessary dependencies and takes care of all the configuration required to get it working.

As you mentioned, rehype-katex requires some extra configuration to work properly with Starlight so having a plugin taking care of everything is great while still allowing users to opt-in to Katex support as it's still not a common use case for most users.

An installation guide and demo is available here.