diff --git a/.gitignore b/.gitignore
index 7dd7cefd964..702ee3d303c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,3 +25,4 @@ package-lock.json
# Misc
_sass/vendors
assets/js/dist
+.jektex-cache
\ No newline at end of file
diff --git a/_config.yml b/_config.yml
index 9b9e2b27bbd..1fb4bd2e0ae 100644
--- a/_config.yml
+++ b/_config.yml
@@ -108,6 +108,13 @@ social_preview_image: # string, local or CORS resources
# boolean type, the global switch for TOC in posts.
toc: true
+# Math equation rendering engine.
+math:
+ # Choose engine for rendering math equations.
+ # mathjax — client-side rendering (loads JavaScript library)
+ # katex — server-side rendering via jektex plugin (faster, no JS required)
+ engine: # [mathjax | katex]
+
comments:
# Global switch for the post-comment system. Keeping it empty means disabled.
provider: # [disqus | utterances | giscus]
@@ -167,6 +174,13 @@ kramdown:
line_numbers: true
start_line: 1
+# Jektex configuration for server-side KaTeX rendering
+jektex:
+ cache_dir: ".jektex-cache" # Cache directory for rendered equations
+ ignore: ["**/*"] # Ignore all by default (enable when math.engine is katex)
+ silent: false # Show rendering progress
+ macros: [] # Global LaTeX macros (e.g., [["\\\\Q", "\\\\mathbb{Q}"]])
+
collections:
tabs:
output: true
diff --git a/_data/origin/basic.yml b/_data/origin/basic.yml
index 2d5298229d3..940aa49c67f 100644
--- a/_data/origin/basic.yml
+++ b/_data/origin/basic.yml
@@ -37,3 +37,6 @@ clipboard:
mathjax:
js: /assets/lib/mathjax/tex-chtml.js
+
+katex:
+ css: /assets/lib/katex/katex.min.css
diff --git a/_data/origin/cors.yml b/_data/origin/cors.yml
index ce99f814109..0d922c90e25 100644
--- a/_data/origin/cors.yml
+++ b/_data/origin/cors.yml
@@ -52,3 +52,6 @@ clipboard:
mathjax:
js: https://cdn.jsdelivr.net/npm/mathjax@3.2.2/es5/tex-chtml.js
+
+katex:
+ css: https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css
diff --git a/_includes/head.html b/_includes/head.html
index a453323b58b..7784a7b96f8 100644
--- a/_includes/head.html
+++ b/_includes/head.html
@@ -102,6 +102,14 @@
{% endif %}
+ {% if page.math %}
+ {% assign math_engine = site.math.engine | default: 'mathjax' %}
+ {% if math_engine == 'katex' %}
+
+
+ {% endif %}
+ {% endif %}
+
diff --git a/_includes/js-selector.html b/_includes/js-selector.html
index 5a80532f82d..7d44307079f 100644
--- a/_includes/js-selector.html
+++ b/_includes/js-selector.html
@@ -65,10 +65,14 @@
{% if page.math %}
-
-
-
-
+ {% assign math_engine = site.math.engine | default: 'mathjax' %}
+ {% if math_engine == 'mathjax' %}
+
+
+
+
+ {% endif %}
+ {%- comment -%} KaTeX is rendered server-side via jektex plugin, only CSS needed {%- endcomment -%}
{% endif %}
diff --git a/_posts/2019-08-08-text-and-typography.md b/_posts/2019-08-08-text-and-typography.md
index a8db26a00ff..8206fd85b01 100644
--- a/_posts/2019-08-08-text-and-typography.md
+++ b/_posts/2019-08-08-text-and-typography.md
@@ -137,17 +137,12 @@ fi;
## Mathematics
-The mathematics powered by [**MathJax**](https://www.mathjax.org/):
+Mathematical expressions can be rendered using either [**MathJax**](https://www.mathjax.org/) or [**KaTeX**](https://katex.org/).
$$
-\begin{equation}
- \sum_{n=1}^\infty 1/n^2 = \frac{\pi^2}{6}
- \label{eq:series}
-\end{equation}
+\sum_{n=1}^\infty 1/n^2 = \frac{\pi^2}{6}
$$
-We can reference the equation as \eqref{eq:series}.
-
When $a \ne 0$, there are two solutions to $ax^2 + bx + c = 0$ and they are
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
diff --git a/_posts/2019-08-08-write-a-new-post.md b/_posts/2019-08-08-write-a-new-post.md
index f048f013c4a..146f7d5d370 100644
--- a/_posts/2019-08-08-write-a-new-post.md
+++ b/_posts/2019-08-08-write-a-new-post.md
@@ -439,9 +439,38 @@ Or adding `render_with_liquid: false` (Requires Jekyll 4.0 or higher) to the pos
## Mathematics
-We use [**MathJax**][mathjax] to generate mathematics. For website performance reasons, the mathematical feature won't be loaded by default. But it can be enabled by:
+Chirpy supports rendering mathematical expressions using either [**MathJax**][mathjax] (client-side) or [**KaTeX**][katex] (server-side) engines.
[mathjax]: https://www.mathjax.org/
+[katex]: https://katex.org/
+
+### Choosing a Rendering Engine
+
+You can configure the math rendering engine in your `_config.yml`:
+
+```yaml
+math:
+ engine: katex # [mathjax | katex]
+```
+
+**MathJax** (default):
+
+- Client-side rendering using JavaScript
+- Larger feature set and better LaTeX compatibility
+- Requires loading JavaScript library (slower initial page load)
+
+**KaTeX**:
+
+- Server-side rendering via the [jektex][jektex] plugin
+- Faster page loads (no JavaScript required)
+- Math is rendered during site build
+- Slightly more limited LaTeX support
+
+[jektex]: https://github.com/yagarea/jektex
+
+### Enabling Math in Posts
+
+For website performance reasons, the mathematical feature won't be loaded by default. Enable it per post:
```yaml
---
@@ -449,6 +478,8 @@ math: true
---
```
+### Syntax
+
After enabling the mathematical feature, you can add math equations with the following syntax:
- **Block math** should be added with `$$ math $$` with **mandatory** blank lines before and after `$$`
@@ -486,10 +517,13 @@ Can be referenced as \eqref{eq:label_name}.
3. \$$ LaTeX_math_expression $$
```
-> Starting with `v7.0.0`, configuration options for **MathJax** have been moved to file `assets/js/data/mathjax.js`{: .filepath }, and you can change the options as needed, such as adding [extensions][mathjax-exts].
+> **MathJax Configuration**: Starting with `v7.0.0`, configuration options for **MathJax** have been moved to file `assets/js/data/mathjax.js`{: .filepath }, and you can change the options as needed, such as adding [extensions][mathjax-exts].
> If you are building the site via `chirpy-starter`, copy that file from the gem installation directory (check with command `bundle info --path jekyll-theme-chirpy`) to the same directory in your repository.
{: .prompt-tip }
+> **KaTeX Configuration**: When using KaTeX, you can configure global macros and other options in the `jektex:` section of `_config.yml`. See the [jektex documentation][jektex] for details.
+{: .prompt-tip }
+
[mathjax-exts]: https://docs.mathjax.org/en/latest/input/tex/extensions/index.html
## Mermaid
diff --git a/_sass/base/_base.scss b/_sass/base/_base.scss
index b512a484cc2..6c2f63fd4ec 100644
--- a/_sass/base/_base.scss
+++ b/_sass/base/_base.scss
@@ -395,6 +395,11 @@ mjx-container {
min-width: auto !important;
}
+/* KaTeX */
+.katex-display {
+ overflow: auto hidden;
+}
+
@media (hover: hover) {
#sidebar ul > li:last-child::after {
transition: top 0.5s ease;
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 50e43ac9d1e..fac660c0684 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -1,5 +1,11 @@
# Changelog
+## [Unreleased]
+
+### Features
+
+* add support for KaTeX server-side math rendering via jektex plugin as an alternative to MathJax
+
## [7.4.1](https://github.com/cotes2020/jekyll-theme-chirpy/compare/v7.4.0...v7.4.1) (2025-10-26)
### Bug Fixes
diff --git a/jekyll-theme-chirpy.gemspec b/jekyll-theme-chirpy.gemspec
index 4694d7d529f..1b4ff9afa60 100644
--- a/jekyll-theme-chirpy.gemspec
+++ b/jekyll-theme-chirpy.gemspec
@@ -31,5 +31,6 @@ Gem::Specification.new do |spec|
spec.add_runtime_dependency "jekyll-archives", "~> 2.2"
spec.add_runtime_dependency "jekyll-sitemap", "~> 1.4"
spec.add_runtime_dependency "jekyll-include-cache", "~> 0.2"
+ spec.add_runtime_dependency "jektex", "~> 0.1.1"
end