asciidoctor-katex

= Asciidoctor KaTeX :source-language: shell // custom :gem-name: asciidoctor-katex :gh-name: jirutka/{gem-name} :gh-branch: master :codacy-id: 58f6aa6e3ef04c8aad1ecd276a8a2c35

ifdef::env-github[] image:https://travis-ci.com/{gh-name}.svg?branch={gh-branch}[Build Status, link="https://travis-ci.com/{gh-name}"] image:https://api.codacy.com/project/badge/Coverage/{codacy-id}["Test Coverage", link="https://www.codacy.com/app/{gh-name}"] image:https://api.codacy.com/project/badge/Grade/{codacy-id}["Codacy Code quality", link="https://www.codacy.com/app/{gh-name}"] image:https://img.shields.io/gem/v/{gem-name}.svg?style=flat[Gem Version, link="https://rubygems.org/gems/{gem-name}"] image:https://img.shields.io/npm/v/{gem-name}.svg?style=flat[npm Version, link="https://www.npmjs.org/package/{gem-name}"] image:https://img.shields.io/badge/yard-docs-blue.svg[Yard Docs, link="http://www.rubydoc.info/github/{gh-name}/{gh-branch}"] endif::env-github[]

This project provides an http://asciidoctor.org/[Asciidoctor] extension for converting block and inline https://asciidoctor.org/docs/user-manual/#activating-stem-support[STEM] in TeX notation (latexmath) to HTML using https://khan.github.io/KaTeX[KaTeX] library right during document conversion (instead of in browser on client-side).

== Requirements

=== Ruby

• https://www.ruby-lang.org/[Ruby] 2.3+ or http://jruby.org/[JRuby] 9.1+
• https://rubygems.org/gems/asciidoctor/[Asciidoctor] 1.5.6+
• https://rubygems.org/gems/katex[katex (gem)] 0.4.3+
• JavaScript engine supported by https://github.com/rails/execjs#execjs[ExecJS]
• https://rubygems.org/gems/thread_safe/[thread_safe] (not required, but recommended for Ruby MRI)

=== Node.js

• https://nodejs.org/[Node.js] 8+
• https://www.npmjs.com/package/@asciidoctor/core[@asciidoctor/core] >=2.0.0 <2.2.0
• https://www.npmjs.com/package/katex[katex (module)] 0.9.0+

== Installation

=== Ruby

Install {gem-name} from Rubygems:

[source, subs="+attributes"] gem install {gem-name}

or to install the latest development version:

[source, subs="+attributes"] gem install {gem-name} --pre

=== Node.js

Install {gem-name} from npmjs.com:

[source, sh, subs="+attributes"] npm install --save {gem-name}

== Usage

=== CLI

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

[source, subs="+attributes"] asciidoctor -r {gem-name} README.adoc

=== Ruby

Just require '{gem-name}'. 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 '{gem-name}', require: false.

=== Node.js

[source, js, subs="+attributes"]

// Load asciidoctor.js and {gem-name}. const asciidoctor = require('@asciidoctor/core')() const asciidoctorKatex = require('{gem-name}')

// 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:

[source, js] 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 http://opensource.org/licenses/MIT/[MIT License]. For the full text of the license, see the link:LICENSE[LICENSE] file.