Asciidoctor KaTeX 2

Asciidoctor extension to render KaTeX mathematics server side to HTML fast with Schmooze. The Nirvana of Math for the web.

• 1. Usage
• 2. Document attributes
• 3. Alternatives
• 4. Why?
• 5. TODO
• 6. Performance test
• 7. Bibliography

1. Usage

Install NPM explained at: https://askubuntu.com/questions/594656/how-to-install-the-latest-versions-of-nodejs-and-npm/971612#971612

Then install the KaTeX Node.js module:

npm install katex@0.10.2

And finally install this extension and use it on our test document test.adoc:

asciidoctor --require asciidoctor-katex-2 test.adoc
xdg-open katex.html

Remember that Node.js is very picky, and KaTeX gets installed in a ./node_modules/ directory, which must be in the current directory!

If you get a katex not found error, make sure that the following works:

node -e 'require("katex")'

Trying to install with npm install --global does not help either: https://stackoverflow.com/questions/15636367/nodejs-require-a-global-module-package

Use this extension directly from this repo for development purposes instead:

asciidoctor --require "$(pwd)/lib/asciidoctor-katex-2.rb" test.adoc

Install this gem locally to ensure that the packaging is correct:

gem build asciidoctor-katex-2
gem install asciidoctor-katex-2

To publish a new version of this gem, first edit the s.version entry on asciidoctor-katex-2.gemspec and then:

version=0.0.0
git tag --message "$version" "$version"
git push --follow-tags
gem build asciidoctor-katex-2
gem push "asciidoctor-katex-2-${version}.gem"

2. Document attributes

• katex-font-size: default: 1.5em. Control the Math font size relative to the regular text, the default was too small: https://stackoverflow.com/questions/50896041/katex-font-size/57355836#57355836

• katex-version: default: 0.10.2. Which version of the KaTeX CSS to use. Should match the KaTeX package executable you installed with NPM

3. Alternatives

Why this is better than:

• MathJax (built-in to Asciidoctor 2.0.10 in latexmath blocks):

  • reflows the page several times, seconds after initial load, which is terrible if you link into a #some-header location of the page

  • not sure can be done server-side, which increases render speed even further and dispenses JavaScript on the browser. The fact that wikimedia uses ugly PhantomJS to SVG hacks for that indicates no: https://github.com/wikimedia/mathoid It even has an extension at: https://github.com/asciidoctor/asciidoctor-extensions-lab/tree/99353d66d9237775e10185787ed969d1a922d6ea/lib/mathoid-treeprocessor

• https://github.com/jirutka/asciidoctor-katex extension at commit 30b037dfe369cec280f07aa2ee5ae365cf1a253c:

  • document render time is too slow because of execjs or the way it was integrated. Benchmark at: asciidoctor/asciidoctor#3338 (comment)

  • you need to manually include docinfo

• AsciiMath: not LaTeX syntax, so larger learning curve and less functionality

• https://github.com/asciidoctor/asciidoctor-mathematical uses https://github.com/gjtorikian/mathematical which converts equations into "SVGs, PNGs, or MathML", so either clunky images that have to be uploaded, or MathML which has low support. KaTeX uses just plain HTML and CSS! Extension at: https://github.com/asciidoctor/asciidoctor-extensions-lab/tree/99353d66d9237775e10185787ed969d1a922d6ea/lib/mathematical-treeprocessor

4. Why?

The dark days of the LaTeX + PDF Empire are counted.

A revolution is coming, in which all people of the world will write their free books, publications and documentation in human readable markup formats that can be converted to HTML.

Proper HTML Mathematics has long been, the final frontier, but it is now upon us.

Join the revolution.

5. TODO

Things already work, but there are two major annoyances that need solving before True Enlightenment:

• make KaTeX \newcommand work across math blocks, only \def works across blocks on KaTeX 0.10.2, upstream issue: KaTeX/KaTeX#2070. Fix merged at: KaTeX/KaTeX#2091 and just waiting for a tag to update KaTeX to.

• Equation #num prefix to caption descriptions which works on xrefs. Does not seem possible from extensions: asciidoctor/asciidoctor#3378? Note that this is however also a limitation of the default :stem: math in Asciidoctor 2.0.10 core as well: asciidoctor/asciidoctor#3354. Upstream fix for the built-in stem at: asciidoctor/asciidoctor#3420.

Less pressing issues:

• ensure that it works with pdflatex as well

• use [stem] or [latexmath] blocks for the Math so that unmodified Asciidoctor documents will just work. This is currently very messy: asciidoctor/asciidoctor#3385 A Treepreprocessor is needed for blocks, but I don’t know how to get the inline one working.

6. Performance test

Compile three documents with similar sizes:

• one with KaTeX math

• the other without mathsx

• the other with MathJax

to compare the effect of the math, and load them in the browser in a header in a header the middle of the file to see how fast they load:

./test-perf.sh

With KaTeX it takes about 4x longer to compile than the others, and the output HTML is 10x larger, but the math renders faster.

7. Bibliography

• asciidoctor/asciidoctor#3338