There's a lot of open issues
Asciidoctor extension that converts latexmath to HTML using KaTeX at build-time
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies

Development

~> 2.3
~> 3.7
~> 0.51.0
~> 0.16
~> 0.9
~> 13.0

Runtime

>= 1.5.6, < 3.0
~> 0.8.0
 Project Readme

Asciidoctor KaTeX

CI Status Test Coverage Codacy Code quality Gem Version npm Version Yard Docs

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

Node.js

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.