asciidoctor-katex

asciidoctor-katex copied to clipboard

= 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://github.com/{gh-name}/workflows/CI/badge.svg[CI Status, link=https://github.com/{gh-name}/actions?query=workflow%3A%22CI%22] 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 is used for testing on CI. ifdef::env-test[] :stem: latexmath stem:[E = mc^2] endif::env-test[]

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

ifndef::npm-readme[] === 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.8.0
• 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 endif::npm-readme[]

• 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

ifndef::npm-readme[] === 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 endif::npm-readme[]

Install {gem-name} from npmjs.com:

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

== Usage

ifndef::npm-readme[] === 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 endif::npm-readme[]

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