Mixin me 25566

# Math in Jekyll with KaTeX

Oct 12, 2020

I have spent days on reading papers related to Byzantine fault tolerant systems, learnt a lot of course, and they also drive me to write about the technical details on how Mixin achieves novel performance on a specific BFT problem, i.e. a directed acyclic graph with almost instant finalizations on simple UTXO transactions.

First of the first is to choose a proper paper writing tool. Most papers use $LaTeX$ to produce typical two column documents, mostly in PDF. I guess the two column tradition for essays is the limited space in printed journals. Journals are printed in very large paper size compared to novels, and to save space they also use smaller font size, so two column will make lines shorter, more readable.

However in a digital and mobile world, I believe a one column paper makes better reading experience in portable devices, and even in computer we have infinite space to display the article, larger font size and one column are possible now. So I decide to produce the final document in HTML, and render formulas with $KaTeX$ engine.

My blog is built with Jekyll, the original writing is Markdown, rendered with kramdown. It’s pretty easy to enable $KaTeX$ server rendering along with kramdown. At first download a proper release (0.11.1) of $KaTeX$, then extract the files in the Jekyll project.

\$ ls _assets/vendor/katex/
fonts  katex.scss


As the above shown, I only keep the fonts directory, and rename the katex.css file to katex.scss. Then modify all url references to the SASS asset-url format.

-  src: url(fonts/KaTeX_AMS-Regular.woff2) format('woff2')
+  src: asset-url('./fonts/KaTeX_AMS-Regular.woff2') format('woff2')


Next is to modify the application.scss to import katex.scss.

//= require katex/katex


Then modify the Gemfile and bundle install.

gem 'kramdown-math-katex'


Finally modify _config.yml.

kramdown:
math_engine: katex


Now $$1 + 1 = 2$$ produces $1 + 1 = 2$, and

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


Produces

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

References