No release in over 3 years
Low commit activity in last 3 years
Asciidoctor extension to render Katex mathematics server side to HTML fast with Schmooze
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies

Runtime

= 2.0.10
 Project Readme

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

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

3. Alternatives

Why this is better than:

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:

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.