= 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
=== Node.js endif::npm-readme[]
== 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[]
// 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
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.