README.md

kramdown math engine for conversion to HTML

This is a converter for kramdown that uses KaTeX and the katex gem to convert math formulas to HTML on the server side.

Note: Until kramdown version 2.0.0 this math engine was part of the kramdown distribution.

Installation

gem install kramdown-math-katex

Usage

require 'kramdown'
require 'kramdown-math-katex'

Kramdown::Document.new(text, math_engine: :katex).to_html

Documentation

The engine uses KaTeX via the katex rubygem to convert TeX math formulas into KaTeX HTML, using ExecJS under the hood. This eliminates the need for client-side math-rendering Javascript. This engine is somewhat similar to the SsKaTeX math engine, but easier to use and suitable for kramdown input from untrusted users.

Requirements for running kramdown with math engine KaTeX:

• Ruby gem kramdown-math-katex
• Ruby gem katex,
• Ruby gem execjs,
• A Javascript engine supported by ExecJS, e.g. via one of
  • Ruby gem therubyracer,
  • Ruby gem therubyrhino,
  • Ruby gem duktape,
  • Node.js.

All these requirements need to be met only if KaTeX is actually used. Note that the katex gem includes KaTeX's Javascript, CSS, and fonts; those do not need to be installed separately. Your HTML templates still need to reference the KaTeX CSS. Consult the katex gem's documentation on how to do that.

A typical KaTeX configuration looks like this:

math_engine: katex
math_engine_opts: {}

math_engine_opts are passed directly to Katex.render. See the gem's documentation for more information.

If you need to sanitize the output, see this example for inspiration.

Development

Clone the git repository and you are good to go. You probably want to install rake so that you can use the provided rake tasks.

License

MIT - see the COPYING file.