Switch math rendering from MathJax to server-side KaTeX#1
Merged
Conversation
Render LaTeX at build time with the jektex plugin instead of loading MathJax in the browser. Posts no longer ship any math JS and equations appear immediately on page load. - Add jektex to the Gemfile (:jekyll_plugins) and configure it in _config.yml; cache lives in .jektex-cache (gitignored). - Override _includes/head.html and _includes/js-selector.html (from Chirpy v7.5.0) to load the KaTeX stylesheet and skip the MathJax scripts when math.engine is "katex". - Add _plugins/katex-inline-math.rb: a pre-render hook that rewrites single-dollar inline math to kramdown's `$$ ... $$` form on pages with `math: true`, so existing posts keep working without edits. - Add .katex-display overflow/padding so wide display equations scroll instead of overflowing the post column.
Records why the theme's MathJax was replaced with build-time KaTeX (jektex), how the rendering pipeline fits together, the authoring rules for math posts, and the step-by-step procedure for re-syncing the vendored _includes overrides when bumping jekyll-theme-chirpy.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replaces client-side MathJax with build-time KaTeX rendering via the jektex plugin. This applies the approach from cotes2020/jekyll-theme-chirpy#2603 directly to this site (since the theme is consumed as a gem).
Gemfile/_config.yml— addjektexto:jekyll_plugins, configure cache dir + ignore globs (feeds/manifests/JS/CSS), and setmath.engine: katex._includes/head.html&_includes/js-selector.html— local overrides of the Chirpy v7.5.0 templates: load the KaTeX stylesheet and skip the MathJax scripts whenmath.engine == 'katex'(still falls back to MathJax if you flip the config)._plugins/katex-inline-math.rb— kramdown only recognises$$ … $$as math, and the old MathJax config papered over this by also scanning the page for$ … $in the browser. This pre-render hook upgrades single-dollar inline math to$$ … $$(skipping fenced code blocks) so all existing posts render unchanged. Only runs on pages withmath: true.assets/css/jekyll-theme-chirpy.scss— add.katex-displayoverflow/padding so wide display equations scroll horizontally instead of overflowing the post column..gitignore— ignore.jektex-cache.Why
Math is now rendered at build time, so posts no longer ship MathJax JS (~1 MB) and equations appear immediately on load instead of flashing raw LaTeX.
Notes
\label/\eqref— confirmed no posts use them.Test plan
bundle install && JEKYLL_ENV=production bundle exec jekyll b -d _sitesucceeds (Ruby 3.4)bundle exec htmlproofer _site --disable-external …passesclass="katex"spans andkatex.min.csslinked; 0katex-errorelements$…$/\( \)/\[ \]outside code/script blocksMathJax/mathjaxscript references in any postfeed.xml/sitemap.xmlstill well-formed and unaffected