Asciidoctor LaTeX defines an extended syntax for the AsciiDoc markup language (AsciiDoc-LaTeX) that closely parallels LaTeX for inline and display mathematical formulas and for environments. Documents written in this extended markup language can be converted into HTML or LaTeX:

Render as HTML

Use asciidoctor-latex -b html foo.adoc to produce foo.html.

Render as LaTeX

Use asciidoctor-latex foo.adoc to produce foo.tex, then use xelatex foo.tex to create foo.pdf.

Below, we describe the main features of AsciiDoc-LaTeX. However, since this document will not render fully in GitHub, you are encouraged to compile it yourself using asciidoctor-latex -b html README.adoc or to consult the README at S3. There is also an online version hosted at shoobox.io, a site for editing and distributing AsciiDoc and AsciiDoc-LaTeX documents.

Asciidoctor LaTeX is developed by James Carlson, Jakub Jirutka, and Dan Allen. Display of mathematical text relies on MathJax.

AsciiDoc-LaTeX renders inline and displayed mathematical, and it supports a construct akin to LaTeX environments for theorems, equations, etc. These and other features are described briefly below and more fully in AsciiDoc-LaTeX environments.

2.1. Inline and displayed formulas

The formula $a^2 + b^2 = c^2$ relates the sides
and hypotenuse of a right triangle.  The formula
\[
\int_0^1 x^n dx = \frac{1}{n+1}
\]
is something we all learn in Calculus

2.2. Environments

  [env.theorem]
  --
 The Diophantine equation
 \[
    x^n + y^n = z^n
 \]
 for $n > 2$ has only trivial solutions
--

2.3. Click blocks

  [env.question]
  --
  What is the speed of light?
  --

  [click.answer]
  --
  300,000 km/sec
  --

3.1. From Rubygems

3.2. From GitHub

$ git clone https://github.com/asciidoctor/asciidoctor-latex.git
$ cd asciidoctor-latex
$ gem build asciidoctor-latex.gemspec
$ gem install *.gem

If you wish to contribute to the asciidoctor-latex project, you should set up your environments to use Jakub Jirutka’s asciidoctor-doctest. At the moment you will need to use the version which handles dialects using

in your Gemfile. Run all tests with rake doctest, or run individual tests with rake doctest:html or rake doctest:tex.

At the moment the tests are for the latex dialect.

Asciidoctor LaTeX processes three dialects of the core AsciiDoc language:

• asciidoc (the core language)

• manuscript

• latex

Asciidoc-latex is the default dialect. Dialects can be set with the :dialect on the command line as in this example:

To set the dialect with the Ruby API, use for example :

Macros can be included in the body of an AsciiDoc-LaTeX file using the texmacro environment, as in the example below.

To include a LaTeX macro file MACRO_FILE, insert the code include_latex_macros::MACRO_FILE[]. Here MACRO_FILE can be a file name or a an absolute or relative path. Included macros work for both the html and tex backends.

To generate a tex file with a minimal header, do:

An alternate css file, data/print.css is provided for printing. It features wider margins and a smaller type size. Copy it to the root of your document folder and use the command asciidoctor-latex -a stylesheet=print.css or more generally asciidoctor-latex -a stylesheet=path_to/print.css.

Asciidoctor-LaTeX’s default form at is :latexmath. To use :stem, put the text :stem: in your file. To turn the switch on and set it to latexmath, say instead of stem:latexmth.

Asciidoctor supports two closely-related math formats, AsciiDoc-LaTeX and AsciiMath. In AsciiDoc-LaTeX, one can write \$ a^2 + b^2 = c^2 \$ and

for in-line and display mathematial text, respectively. You will need to express dollar-denominated currency using escaped dollar signs, as in the sentence, "He paid \$100 for that theorem." In AsciiMath, one writes stem:[ a^2 + b^2 = c^2 ] and

AsciiDoctor LaTeX supports an env construct that maps to LaTeX environments. Thus

renders as an automatically numbered theorem. Environments can contain in-line and display mathematics, e.g.,

There is complete freedom in parameter NAME of [env.NAME], Thus,one can write

or

One can make cross references by labeling the environment as in

then referencing it later as <<mathjoke1>>

Certain environments receive special treatment. For numbered equations, use [env.equation] like this

An equation number will be displayed only when a label for cross-referencing is provided, e.g.,

For sets of equations, use [env,equationalign]: