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.
siddharth's space 