Skip to content
Asciidoctor extension to render KaTeX mathematics server side to HTML fast with Schmooze. The Nirvana of Math for the web.
Ruby Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
.gitignore
LICENSE
README.adoc
asciidoctor-katex-2.gemspec
test-perf.sh
test.adoc

README.adoc

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

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: https://github.com/asciidoctor/asciidoctor/issues/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.

You can’t perform that action at this time.