Asciidoctor KaTeX
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
-
Asciidoctor 1.5.6+
-
katex (gem) ~> 0.8.0
-
JavaScript engine supported by ExecJS
-
thread_safe (not required, but recommended for Ruby MRI)
Node.js
-
Node.js >=8
-
@asciidoctor/core >=2.0.0 <2.2.0
-
katex (module) >=0.9.0
Installation
Ruby
Install asciidoctor-katex from Rubygems:
gem install asciidoctor-katexor to install the latest development version:
gem install asciidoctor-katex --preNode.js
Install asciidoctor-katex from npmjs.com:
npm install --save asciidoctor-katexUsage
CLI
If you invoke Asciidoctor from command-line, use option -r to load the extension:
asciidoctor -r asciidoctor-katex README.adocRuby
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, usegem '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)- katex
-
The katex object to use for rendering. Defaults to
require('katex'). - requireStemAttr
-
Whether to require
stemattribute to be defined (Asciidoctor’s standard behaviour). Set tofalseto process latexmath even whenstemattribute is not defined. Default istrue.
Note that the default stem type hard-coded by Asciidoctor isasciimath(notlatexmath), so[stem]block andstem:[...]macro will not be rendered anyway (only[latexmath]block andlatexmath:[...]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.