LaTeX for Jekyll from GitHub Pages to GitLab Pages

22 May 2022 • Computer Touching

About a year ago I posted about using K A T E X in a Jekyll site for GitHub Pages. This had been an unsatisfying solution to me, since GH Pages restricts Jekyll plugins to their allowlist, meaning that if I didn’t want to manually add precompiled HTML pages, LaTeX rendering would have to be done client-side using JavaScript. Furthermore, I found out that kramdown, the Markdown compiler that GH Pages uses, has built-in support for KaTeX without needing to explicitly include additional Liquid tags, but GH Pages, too, has overridden configurations needed to enable using KaTeX as well!

On the other hand, GitLab Pages is much less restrictive with what’s allowed, because the build process is literally just a CI script. This bypasses the plugins allowlist, but not the configuration overrides, which are from the github-pages Gem. The first thing to do, then, is to forego the Gem and include only the plugins I need in Gemfile. On top of that, I have the Gems required to use KaTeX as kramdown’s math engine.

source "https://rubygems.org"

gem "jekyll-feed"
gem "jekyll-gist"
gem "jekyll-paginate"
gem "jekyll-remote-theme"
gem "jekyll-scholar"
gem "katex"
gem "kramdown-math-katex"

github-pages also specifies a number of default configurations, but most of these are either Jekyll defaults or undesirable (namely allowlist plugins and kramdown configurations). I also already have a number of configurations set from when I was using GH Pages. The below are the only missing configurations that needed adding in _config.yml to include the Jekyll plugins and to enable using KaTeX for kramdown. I use the KaTeX option to output MathML so that I don’t need to include a stylesheet.

plugins:
  - jekyll-feed
  - jekyll-gist
  - jekyll-paginate
  - jekyll-remote-theme
  - jekyll-scholar

kramdown:
  math_engine: katex
  math_engine_opts:
    output: mathml

Finally, to use GitLab Pages, there needs to be a CI configuration script to install Node.js (which kramdown-math-katex needs to run KaTeX) and to build the Jekyll site.

image: ruby:latest

pages:
  script:
    - apt-get update && apt-get -y install nodejs
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public

Now inline LaTeX works everywhere using double dollar signs: $$\int_{\partial \Omega} \omega = \int_{\Omega} d\omega$$ yields ∫∂Ωω=∫Ωdω\int_{\partial \Omega} \omega = \int_{\Omega} d\omega. There aren’t any delimiters for display-style math, but you can always add \displaystyle to a block of LaTeX.

∫∂Ωω=∫Ωdω\displaystyle \int_{\partial \Omega} \omega = \int_{\Omega} d\omega

References

 Jekyll  blog  LaTeX