Asciidoctor KaTeX

This project provides an Asciidoctor extension for converting block and inline STEM in TeX notation (latexmath) to HTML using KaTeX library right during document conversion (instead of in browser on client-side).

Requirements

Ruby

Ruby 2.3+ or JRuby 9.1+
Asciidoctor 1.5.6+
katex (gem) ~> 0.8.0
JavaScript engine supported by ExecJS
thread_safe (not required, but recommended for Ruby MRI)

Node.js

Node.js >=8
@asciidoctor/core >=2.0.0 <2.2.0
katex (module) >=0.9.0

Installation

Ruby

Install asciidoctor-katex from Rubygems:

gem install asciidoctor-katex

or to install the latest development version:

gem install asciidoctor-katex --pre

Node.js

Install asciidoctor-katex from npmjs.com:

npm install --save asciidoctor-katex

Usage

CLI

If you invoke Asciidoctor from command-line, use option -r to load the extension:

asciidoctor -r asciidoctor-katex README.adoc

Ruby

Just require 'asciidoctor-katex'. However, if you don’t want the extension to be automatically registered in Asciidoctor, require 'asciidoctor/katex/treeprocessor' instead.

Important

Bundler automatically requires all the specified gems. To prevent it, use
gem 'asciidoctor-katex', require: false.

Node.js

// Load asciidoctor.js and asciidoctor-katex.
const asciidoctor = require('@asciidoctor/core')()
const asciidoctorKatex = require('asciidoctor-katex')

// See documentation at the end of this section.
const options = {
  katexOptions: {
    macros: {
      "\\RR": "\\mathbb{R}",
    },
  },
}

// Configure the extension and register it into global registry.
asciidoctorKatex.register(asciidoctor.Extensions, options)

// Convert the content to HTML.
const content = `
:stem: latexmath

Do some math: stem:[E = mc^2]
`
const html = asciidoctor.convert(content)
console.log(html)

You may also register the extension into a custom extensions registry:

const registry = asciidoctor.Extensions.create()
asciidoctorKatex.register(registry, options)

Options:

katex: The katex object to use for rendering. Defaults to require('katex').
requireStemAttr: Whether to require stem attribute to be defined (Asciidoctor’s standard behaviour). Set to false to process latexmath even when stem attribute is not defined. Default is true.
Note that the default stem type hard-coded by Asciidoctor is asciimath (not latexmath), so [stem] block and stem:[...] macro will not be rendered anyway (only [latexmath] block and latexmath:[...] macro).
katexOptions: The default options for katex.render(). Defaults to empty object.

License

This project is licensed under MIT License. For the full text of the license, see the LICENSE file.