Running KaTeX on Jekyll?

Question

Are a couple of days that I'm trying to use KaTeX instead of MathJax on my static Jekyll website. I tried a lot of suggestion found on internet without success. The last one is the jekyll-katex plugin. I followed all the steps in the readme.

This is my current Gemfile:

source "https://rubygems.org"

gem "jekyll", "~> 3.8.3"
gem "minima", "~> 2.0"

group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.6"
  gem 'jekyll-katex', "~> 0.2"
end

# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby]

# Performance-booster for watching directories on Windows
gem "wdm", "~> 0.1.0" if Gem.win_platform?

This is the relevant part in my current _config.yml:

markdown: kramdown
theme: minima
plugins:
  - jekyll-feed
  - jekyll-katex

When I run bundle exec jekyll serve I receive this error:

bundler: failed to load command: jekyll (/usr/local/bin/jekyll)
Bundler::GemRequireError: There was an error while trying to load the gem 'jekyll-katex'.
Gem Load Error is: undefined method `[]' for nil:NilClass
Backtrace for gem load error is:
/var/lib/gems/2.5.0/gems/jekyll-katex-0.2.0/lib/jekyll-katex/configuration.rb:22:in `js_path'
/var/lib/gems/2.5.0/gems/jekyll-katex-0.2.0/lib/jekyll/tags/katex.rb:14:in `<class:Katex>'
/var/lib/gems/2.5.0/gems/jekyll-katex-0.2.0/lib/jekyll/tags/katex.rb:12:in `<module:Tags>'
/var/lib/gems/2.5.0/gems/jekyll-katex-0.2.0/lib/jekyll/tags/katex.rb:7:in `<module:Jekyll>'
/var/lib/gems/2.5.0/gems/jekyll-katex-0.2.0/lib/jekyll/tags/katex.rb:6:in `<top (required)>'
/var/lib/gems/2.5.0/gems/jekyll-katex-0.2.0/lib/jekyll-katex.rb:7:in `require'
/var/lib/gems/2.5.0/gems/jekyll-katex-0.2.0/lib/jekyll-katex.rb:7:in `<top (required)>'
/usr/local/lib/site_ruby/2.5.0/bundler/runtime.rb:81:in `require'
/usr/local/lib/site_ruby/2.5.0/bundler/runtime.rb:81:in `block (2 levels) in require'
/usr/local/lib/site_ruby/2.5.0/bundler/runtime.rb:76:in `each'
/usr/local/lib/site_ruby/2.5.0/bundler/runtime.rb:76:in `block in require'
/usr/local/lib/site_ruby/2.5.0/bundler/runtime.rb:65:in `each'
/usr/local/lib/site_ruby/2.5.0/bundler/runtime.rb:65:in `require'
/usr/local/lib/site_ruby/2.5.0/bundler.rb:114:in `require'
/var/lib/gems/2.5.0/gems/jekyll-3.8.3/lib/jekyll/plugin_manager.rb:51:in `require_from_bundler'
/var/lib/gems/2.5.0/gems/jekyll-3.8.3/exe/jekyll:11:in `<top (required)>'
/usr/local/bin/jekyll:23:in `load'
/usr/local/bin/jekyll:23:in `<top (required)>'
/usr/local/lib/site_ruby/2.5.0/bundler/cli/exec.rb:74:in `load'
/usr/local/lib/site_ruby/2.5.0/bundler/cli/exec.rb:74:in `kernel_load'
/usr/local/lib/site_ruby/2.5.0/bundler/cli/exec.rb:28:in `run'
/usr/local/lib/site_ruby/2.5.0/bundler/cli.rb:424:in `exec'
/usr/local/lib/site_ruby/2.5.0/bundler/vendor/thor/lib/thor/command.rb:27:in `run'
/usr/local/lib/site_ruby/2.5.0/bundler/vendor/thor/lib/thor/invocation.rb:126:in `invoke_command'
/usr/local/lib/site_ruby/2.5.0/bundler/vendor/thor/lib/thor.rb:387:in `dispatch'
/usr/local/lib/site_ruby/2.5.0/bundler/cli.rb:27:in `dispatch'
/usr/local/lib/site_ruby/2.5.0/bundler/vendor/thor/lib/thor/base.rb:466:in `start'
/usr/local/lib/site_ruby/2.5.0/bundler/cli.rb:18:in `start'
/usr/lib/ruby/gems/2.5.0/gems/bundler-1.16.2/exe/bundle:30:in `block in <top (required)>'
/usr/local/lib/site_ruby/2.5.0/bundler/friendly_errors.rb:124:in `with_friendly_errors'
/usr/lib/ruby/gems/2.5.0/gems/bundler-1.16.2/exe/bundle:22:in `<top (required)>'
/usr/local/bin/bundle:23:in `load'
/usr/local/bin/bundle:23:in `<main>'
Bundler Error Backtrace:

  /usr/local/lib/site_ruby/2.5.0/bundler/runtime.rb:84:in `rescue in block (2 levels) in require'
  /usr/local/lib/site_ruby/2.5.0/bundler/runtime.rb:80:in `block (2 levels) in require'
  /usr/local/lib/site_ruby/2.5.0/bundler/runtime.rb:76:in `each'
  /usr/local/lib/site_ruby/2.5.0/bundler/runtime.rb:76:in `block in require'
  /usr/local/lib/site_ruby/2.5.0/bundler/runtime.rb:65:in `each'
  /usr/local/lib/site_ruby/2.5.0/bundler/runtime.rb:65:in `require'
  /usr/local/lib/site_ruby/2.5.0/bundler.rb:114:in `require'
  /var/lib/gems/2.5.0/gems/jekyll-3.8.3/lib/jekyll/plugin_manager.rb:51:in `require_from_bundler'
  /var/lib/gems/2.5.0/gems/jekyll-3.8.3/exe/jekyll:11:in `<top (required)>'
  /usr/local/bin/jekyll:23:in `load'
  /usr/local/bin/jekyll:23:in `<top (required)>'

Any help is appreciated.

Note that my real goal is to have a simple way to use KaTeX with Jekyll. This means that if you have other solutions that don't involve this plugin you could post as well. — gvgramazio, Jun 16 '18 at 18:38

score 4 · Answer 1 · answered Mar 06 '21 at 22:28

It's been a while now since OP asked the question, but after a whole day of trial and error from various sources on integrating KaTeX into my Jekyll static site (with the additional constraint that I use GitHub pages), the steps from this blog post got it working for me. I have decided to reproduce it here below because it answers the question, other users may find it useful, and because the blog is not easy to find (it was buried within the issues section on the jekyll-katex GitHub repo, and not accessible via Google searches):

Auto-rendering of KaTeX with Jekyll, which works with GitHub pages.

Add the following lines to your _config.yml file:

kramdown:
  math_engine: katex

Add the following code snippet inside the <head> tags in _includes/head.html, paying careful attention to indentation:

  <!--KaTeX-->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.css" integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X" crossorigin="anonymous">
  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.js" integrity="sha384-g7c+Jr9ZivxKLnZTDUhnkOnsh30B4H0rpLUpJ4jAIKs4fnJI+sEnkvrMWph2EDg4" crossorigin="anonymous"></script>
  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/contrib/auto-render.min.js" integrity="sha384-mll67QQFJfxn0IYznZYonOWZ644AWYC+Pt2cHqMaRhXVrursRwvLnLaebdGIlYNa" crossorigin="anonymous"></script>
  <script>
      document.addEventListener("DOMContentLoaded", function() {
          renderMathInElement(document.body, {
              // ...options...
          });
      });
  </script>

So that _includes/head.html looks like:

<head>

  ...

  <!--KaTeX-->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.css" integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X" crossorigin="anonymous">
  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.js" integrity="sha384-g7c+Jr9ZivxKLnZTDUhnkOnsh30B4H0rpLUpJ4jAIKs4fnJI+sEnkvrMWph2EDg4" crossorigin="anonymous"></script>
  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/contrib/auto-render.min.js" integrity="sha384-mll67QQFJfxn0IYznZYonOWZ644AWYC+Pt2cHqMaRhXVrursRwvLnLaebdGIlYNa" crossorigin="anonymous"></script>
  <script>
      document.addEventListener("DOMContentLoaded", function() {
          renderMathInElement(document.body, {
              // ...options...
          });
      });
  </script>

</head>

To use the KaTeX in a .md blog post, insert katex: True. For example:

---
layout: post
title: KaTeX with Jekyll
katex: True
---
inline: $$f(x) = \int_{-\infty}^\infty \hat f(\xi)\,e^{2 \pi i \xi x} \,d\xi$$
display mode (centered):

$$f(x) = \int_{-\infty}^\infty \hat f(\xi)\,e^{2 \pi i \xi x} \,d\xi$$

Everything inside the $$ signs will now be displayed as KaTeX.

score 1 · Accepted Answer · answered Jun 16 '18 at 22:29

I did it! However I didn't use jekyll-katex plugin but jekyll-katek-block. I simply followed the instruction in its readme. Basically the only steps needed are:

Put katex_block.rb in _plugins folder
Store katex.min.js anywhere in your website. Default is /public/js/katex.min.js, otherwise you have to modify your _config.yml adding
```
katex:
  path_to_js: "./your/path/to/katex/js"
```
(almost optional) Link katek.min.css and fonts.

katex.min.js, katex.min.css, and fonts can be downloaded from KaTeX GitHub page.

As I said my purpose was to run KaTeX with Jekyll and this method works. However, if someone else is able to make jekyll-katex works, since it was the original request, I'll mark it as accepted.

I ran into similar issues. Does using `jekyll-katex-block` still work for you instead of `jekyll-katex`? — microhaus, Mar 06 '21 at 19:47
@microhaus it seems the bug was fixed later but I didn’t try again and I don’t know for sure. — gvgramazio, Mar 06 '21 at 19:56

score 0 · Answer 3 · answered Jun 19 '18 at 10:06

Regarding the jekyll-katex plugin, it seems that I've encountered in a bug of the new version due to new configuration options. I posted an issue on the github repo of the project and it will be soon fixed. Until then, it seems that a workaround (according to the developer) should be to add a blank configuration options to _config.yml:

katex:

Remark: When the bug will be solved I'll update this answer.

Running KaTeX on Jekyll?

3 Answers3