Math in Markdown and AsciiDoc

Did you know that you can include LaTeX snippets in Markdown and AsciiDoc documents? For writing a scientific or technical document pure LaTeX is still the best choice. But if you want to write a Markdown or AsciiDoc document that needs to contain some math snippets, you can. Here is how.

Both Markdown and AsciiDoc support embedding LaTeX snippets. Markdown supports this with $…latex…$ for inline and

$$...latex...$$

for blocks.

AsciiDoc is a bit more verbose and uses stem:[…latex…] for inline and

[stem]
++++
...latex...
++++

for blocks. And for AsciiDoc we should also add :stem: latexmath at the top of your document.

The …latex… part could for example be the well known formula for kinetic energy:

in Markdown: $E_k = \frac{1}{2}mv^2$
in AsciiDoc: stem:[E_k = \frac{1}{2}mv^2]

Examples

See the following examples:

Gradient_in_spherical_coordinates.md - renders correctly in IntelliJ, but not in Codeberg
Gradient_in_spherical_coordinates.adoc - renders correctly in IntelliJ, but not in Codeberg
Gradient_in_spherical_coordinates_codeberg_version.md - renders correctly in IntelliJ and in Codeberg, this one should render correctly in your browser!

Markdown

Markdown files render automatically at/in Codeberg, GitHub, GitLab, and in IntelliJ.

Although not all instructions may render correctly in all. Codeberg for instance does not support the $$ with multiple lines in it yet (tested 2025-12-05). But the IntelliJ plugin does render both Markdown examples above correctly.

AsciiDoc

With the with AsciiDoc plugin it renders correctly in IntelliJ. However, converting the given AsciiDoc example to PDF does not work correctly in IntelliJ yet (tested with IntelliJ IDEA 2025.2.5 (Ultimate Edition) on Ubuntu 24.04.3 LTS). But alternatively you can use the Asciidoctor Mathematical extension to generate a .pdf file from your .adoc file.

One way of doing that is using the Asciidoctor Docker Container mentioned in the Install paragraph.

This is how:

$ docker run -it -u $(id -u):$(id -g) -v <your directory>:/documents/ asciidoctor/docker-asciidoctor

Example:

$ docker run -it -u $(id -u):$(id -g) -v .:/documents/ asciidoctor/docker-asciidoctor

Sometimes it is needed to set the following environment variable

$ export XDG_CACHE_HOME=/tmp/.cache

and finally

$ mkdir target
$ asciidoctor-pdf -r asciidoctor-mathematical -D target -a imagesoutdir=target/math-cache Gradient_in_spherical_coordinates.adoc

This is the resulting .pdf file: Gradient_in_spherical_coordinates.pdf

NB. Unfortunately apparently asciidoctor-pdf does not support the \newcommand{\dd}{\mathrm{d}} instruction (yet). So in this .adoc example file I do not use it. If you want to see how it could be used see the non-Codeberg .md example file above.

More Info

See Math in Markdown and Asciidoc.