I had quite a lot of challenges getting math to render in AsciiDoctorPDF. The documentation relating to this is also confusing. It turns out that for converting asciidoc to PDF which is what I am interested in (i.e., output format = PDF) AsciiDoctorPDF uses `asciidoctor-mathematical`

library. The MathJax library *does not apply* when output format = PDF. I wasn’t able to install `asciidoctor-mathematical`

successfully on my Mac but the Docker image `docker-asciidoctor`

provided a solution until I ran into `gsub!': asciidoctor: FAILED to load AsciiDoc document - can't modify frozen String (FrozenError)`

error. This was fixed in `asciidoctor-mathematical`

0.3.1 (see this) and related changes continue to be made (see this). Using `stem:asciimath`

did not work well for me. Its better to set

:stem: latexmath

in your adoc file. There are many other issues I ran into such as equation numbers appearing to the left instead of right. They appear to have been fixed with successive releases.

One issue that remains unresolved has to do with `:imagesdir:`

This attribute controls the directory where AsciiDoctorPDF expects to find images. What happens is that `asciidoctor-mathematical`

does not know anything about `:imagesdir:`

The way `asciidoctor-mathematical`

works is that it renders the math as a .png and then the parent `asciidoctor`

-pdf program inserts the png into the document like any other png. That is my understanding. The problem is that if you have set `:imagesdir:`

to say `images`

the parent program looks for the png under that directory but `asciidoctor-mathematical`

outputs the pngs into the working directory. The way I have been working around this is a two-step process in which I run `asciidoctor-pdf`

*twice*. In the first pass I let `asciidoctor-mathematical`

generate the images (pngs) and before running `asciidoctor-pdf`

again, *I copy over the images to the correct :imagesdir: directory.* That’s what

`asciidoctor-mathematical`

should be doing in the first place.An example equation looks like this:

[latexmath#equation1, reftext='Equation {chapter}.{counter:equation}'] ++++ \begin{equation} sig = enc(\phi(M), s) \end{equation} ++++

This assumes you have defined two counters in your adoc like so:

:chapter: 3 :equation: 0

Now you will refer to this equation as `<<equation1>>`

in your adoc. And the `reftext`

controls what text will be inserted in place of `<<equation1>>`

. The `counter`

keyword increments the counter so that you get what you want. The attributes above have nothing to do with equation numbering – the number that appears next to an equation. To get that there is one additional attribute you should define in the adoc:

:eqnums: all

This still does not fix one thing which is the format you want to use for equation numbers. The `reftext`

only controls the string used to refer the equation. It seems we have no control over the format of equation numbers. E.g., I wanted equations to be numbered `{chapter}.{equation-number}`

and looks like it is not possible to insert the `{chapter}.`

prefix before the equation number. TL;DR is that if your document is math heavy AsciiDoctorPDF might not be the right choice in which to write it.

It look a long time to discover all the nuances as the documentation is not very good. Hopefully it helps someone else.