Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/cirosantilli/asciidoctor-katex-2

Asciidoctor extension to render KaTeX mathematics server side to HTML fast with Schmooze. The Nirvana of Math for the web. Also consider: Also consider: https://github.com/cirosantilli/ourbigbook
https://github.com/cirosantilli/asciidoctor-katex-2

Last synced: 3 days ago
JSON representation

Asciidoctor extension to render KaTeX mathematics server side to HTML fast with Schmooze. The Nirvana of Math for the web. Also consider: Also consider: https://github.com/cirosantilli/ourbigbook

Awesome Lists containing this project

README 

        
= Asciidoctor KaTeX 2

:idprefix:

:idseparator: -

:nofooter:

:sectanchors:

:sectlinks:

:sectnumlevels: 6

:sectnums:

:toc-title:

:toc: macro

:toclevels: 6



Asciidoctor extension to render KaTeX mathematics server side to HTML xref:performance-test[fast] with https://github.com/Shopify/schmooze[Schmooze]. The Nirvana of Math for the web.



toc::[]



== 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 [email protected]

....



And finally install this extension and use it on our test document link: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 link: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"

....



== 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



== 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 https://github.com/rails/execjs[execjs] or the way it was integrated. Benchmark at: https://github.com/asciidoctor/asciidoctor/pull/3338#issuecomment-502045350

** 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



== 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.



== 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: https://github.com/KaTeX/KaTeX/issues/2070[]. Fix merged at: https://github.com/KaTeX/KaTeX/pull/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: https://github.com/asciidoctor/asciidoctor/issues/3378[]? Note that this is however also a limitation of the default `:stem:` math in Asciidoctor 2.0.10 core as well: https://github.com/asciidoctor/asciidoctor/issues/3354[]. Upstream fix for the built-in stem at: https://github.com/asciidoctor/asciidoctor/pull/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: 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.



== 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.



== Bibliography



* https://github.com/asciidoctor/asciidoctor/pull/3338