how to enable asciimath formula using mathjax in asciidoctorJ

Upasana | May 23, 2019 | 2 min read | 128 views

In this tutorial we will learn how to integrate asciimath diagrams using AsciidoctorJ and any compatible browser.

Lets consider we have the following sample asciidoc file that contains asciimath markup.

Sample Asciidoc File

= My Diabolical Mathmatical Opus
Jamie Moriarty

sample1

asciimath:[sqrt(4) = 2]
stem:[sqrt(4) = 2]

We can use the below java program that converts the given asciidoc document into HTML5 output.

Java program to convert Asciidoc to HTML5

Attributes attributes = AttributesBuilder.attributes()
            .math("asciimath")  (1)
            .get();

Options options = OptionsBuilder.options()
            .attributes(attributes)
            .docType("article")
            .safe(SafeMode.SERVER)
            .backend("html5")
            .get();

asciidoctor.convert(asciiDoc, options);

1	Enable support for `asciimath` extension

Here we are using this version of asciidoctorj program

build.gradle

compile('org.asciidoctor:asciidoctorj:2.0.0')

Output on browser

sample1

\$sqrt(4) = 2\$
\$sqrt(4) = 2\$

We can see that AsciidoctorJ has escaped the asciimath input using \$.

Using mathjax to render asciimath inside browser

Asciidoctor support asciimath and latexmath syntax and the output produced by asciimath can be rendered on browser using http://asciimath.org js library (other asciimath libraries can also be used).

We can download the mathjax js library from https://www.mathjax.org

We need to configure MathJax to use \$ as the delimiter for asciimath formulas using the following configuration:

Mathjax configuration

<script type="text/x-mathjax-config">
    MathJax.Hub.Config({
       asciimath2jax: {
           delimiters: [['\\$','\\$'], ['`','`']]
       }
    });
</script>

Here is the complete HTML template that we can use to render asciimath in AsciidoctorJ

HTML Template

<html>
<head>
<script type="text/x-mathjax-config">
    MathJax.Hub.Config({
       asciimath2jax: {
           delimiters: [['\\$','\\$'], ['`','`']]
       }
    });
</script>
<script type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML">
</script>
...
</head>
//rest of html
</html>

We can refer to this section of Asciidoctor documents for activating support of asciimath inside asciidocs: https://asciidoctor.org/docs/user-manual/#activating-stem-support