Use MathJax (Latex or AsciiMath) in your AsciiDoc projects 馃馃殌
馃摑 Example
adoc-math has zero depependencies! So it鈥檚 fine to install it globally[1] 馃槢
pip3 install --user --upgrade adoc-math
adoc-math-setup # will call `npm i -g mathjax@3` and `npm link`I think of AsciiDoc as a markup syntax somewhere between Markdown and LaTeX. It originated with a Python implementation, but afaik that isn鈥檛 actively developed, and the reference implementation is Asciidoctor in Ruby.
AsciiDoc allows you to write a document and then output it in:
-
html (Asciidoctor)
-
pdf (Asciidoctor-Pdf)
and many other formats! There is even an Asciidoctor.js version (an automated translation of the Ruby code to JavaScript).
Putting LaTeX equations in other places than a TeX document is not so easy. There are two main libraries for this:
STEM stands for Science, Technology, Engineering, Mathematics, basicaly LaTeX. There are two sections in the AsciiDoc documentation on STEM:
The TLDR is:
-
In Asciidoctor (i.e. Html output), you can include math with
stem:[ x+y]. In the browser, MathJax is used to render the math, and frankly, it looks beautiful. -
Since MathJax uses browser fonts and Css, it doesn鈥檛 work in Pdfs. There is an official asciidoctor-mathematical package that provides this support. However, it is extremely quirky, and the ouput doesn鈥檛 look very good (see a comparison of adoc-math and asciidoctor-mathematical in the Example)
-
Some more references:
-
That鈥檚 where adoc-math comes in! I decided for:
-
a Python package that searches for naturally-looking latex cells (e.g.
$a+b$), calls MathJax to create an svg, and replaces the cells with an image of the svg
I couldn鈥檛 use KaTeX because only MathJax has an Svg output (see KaTeX/KaTeX#375).
Inline cells: |
$x + y$ [...options] |
Block cells: |
$$ [...options] x + y $$ |
For more examples, see the Example.
Why isn鈥檛
adoc-mathwritten in Ruby?
I don鈥檛 speak Ruby 馃槥 If you would like to translate this library to Ruby, or at least an AsciiDoc macro that can get replaced by an image, so we cant get rid of the extra metacompilation step, I鈥檇 be more than happy to help!
Why aren鈥檛 inline cells avaiable "in line", such as "Let
$x$ be a integer."?
This decision was chosen very early during development. It makes the parsing logic easier, and reduces the change that a paragraph containing two dollar signs will get replaced by LaTeX. In theory, it would be possible to add this; however, the output will still have at least one linebreak, since we want to comment out the source math. We would probably be better off just making an Asciidoc macro (stem[], m[], or something similar), but we need a Ruby speaker!
What are
exunits?
An ex unit is equal to the font size (height) of the lowercase x character. So it鈥檚 roughly one half of a line? It鈥檚 used in Mathjax鈥檚 svgs (as the width, height and vertical-align) and in adoc-math to adjust the vertical-align.
What about Windows?
I tried to be conscious of non-Posix platforms, but haven鈥檛 tested in on Windows. Any behavioral discrepancies would be considered valid issues.
Can I reference a cell, or add a caption to a block cell?
Yes! Check out the Example.
It鈥檚 annoying having to uncomment the source math to edit it.
You can use a pre-post pattern. pre.adoc will be your source code, and post.adoc will be the output of adoc-math / input to asciidoctor(-pdf)?. Run cpy pre.adoc post.adoc before every invocation to adoc-math.
How come inline cells become part of the sentence when they are on a separate line?
In AsciiDoc, you need to separate two blocks with at least one empty line. 馃檪
Does
adoc-mathwork with an Html output?
This first version is geared towards Pdf output. Happy to add more powerful support for Html outputs in the future (e.g., just use the native stem:[] macro for Html, so we can use basic MathJax with browser fonts and Css (instead of svgs)).
Can I use a different font?
Can I make my math thinner/thicker?
The created svgs have a property called stroke-width that can adjust this. Unfortunately, it is currently set to 0, so it is not possible to make it thinner. In theory it should be possible to make it thicker by increasing that value. svg_transforming.py would be the place for that; or create an issue and I鈥檒l add it.
I get a MODULE_NOT_FOUND error.
MathJax probably cannot be found. Try running adoc-math-setup.
My AsciiMath fractions are too large!
It seems that AsciiMath interprets fractions in displaystyle rather than textstyle (\dfrac{}{} rather than \tfrac{}{} or even \frac{}{}, see StackExchange).
I haven鈥檛 found a good solution to this yet. If you have any ideas, please let me know! Note that if you have a singleton fraction ($a/b$ amath) you can scale it down with $a/b$ amath, scale = 60% (or just use tex).
Math in bullet points causes my text not to be aligned with the bullet point.
Try playing around with the positioning and vertical align offset. In this example, just adding dont_position to this cell鈥檚 attributes fixes the issue:
Adding math in a 4th-order bullet point causes weird rendering.
In AsciiDoc, literal blocks can be delimited (created) with ---- or ****. So if you need to have something like:
* one ** two *** three **** $1 + 1 = 4$
AsciiDoc will recognize the **** as an opening of a literal block.
The solution to this is to add something after the ****. This uses the builtin {empty}:
* one
** two
*** three
**** {empty}
$1 + 1 = 4$