feat(maths): add KaTeX support for server-side math rendering

.gitignore

@@ -25,3 +25,4 @@ package-lock.json
 # Misc
 _sass/vendors
 assets/js/dist
+.jektex-cache

_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

_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

_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

_includes/head.html

@@ -102,6 +102,14 @@
     <link rel="stylesheet" href="{{ site.data.origin[type].glightbox.css | relative_url }}">
   {% endif %}
 
+  {% if page.math %}
+    {% assign math_engine = site.math.engine | default: 'mathjax' %}
+    {% if math_engine == 'katex' %}
+      <!-- KaTeX CSS for server-side rendering -->
+      <link rel="stylesheet" href="{{ site.data.origin[type].katex.css | relative_url }}">
+    {% endif %}
+  {% endif %}
+
   <!-- Scripts -->
 
   <script src="{{ '/assets/js/dist/theme.min.js' | relative_url }}"></script>

_includes/js-selector.html

@@ -65,10 +65,14 @@
 <script defer src="{{ script | relative_url }}"></script>
 
 {% if page.math %}
-  <!-- MathJax -->
-  <script src="{{ '/assets/js/data/mathjax.js' | relative_url }}"></script>
-  <script async src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=es6"></script>
-  <script id="MathJax-script" async src="{{ site.data.origin[type].mathjax.js | relative_url }}"></script>
+  {% assign math_engine = site.math.engine | default: 'mathjax' %}
+  {% if math_engine == 'mathjax' %}
+    <!-- MathJax -->
+    <script src="{{ '/assets/js/data/mathjax.js' | relative_url }}"></script>
+    <script async src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=es6"></script>
+    <script id="MathJax-script" async src="{{ site.data.origin[type].mathjax.js | relative_url }}"></script>
+  {% endif %}
+  {%- comment -%} KaTeX is rendered server-side via jektex plugin, only CSS needed {%- endcomment -%}
 {% endif %}
 
 <!-- Pageviews -->

_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} $$

_posts/2019-08-08-write-a-new-post.md

@@ -439,16 +439,47 @@ 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
 ---
 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

_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;

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

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