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