asciidoctor-latexmath

Offline latexmath rendering for Asciidoctor documents powered by your local LaTeX toolchain.

• asciidoctor-latexmath
  • Table of Contents
  • Overview
  • Features
  • Security Note
  • How It Works
  • Output Formats
  • Prerequisites
  • Installation
    • Using RubyGems
    • Using Bundler
    • From Source
  • Quick Start
  • Document Attributes
    • Document-level configuration
      • Font size control
    • Element attributes & options
  • Caching
  • Why asciidoctor-latexmath?
  • Accessibility & Semantics
  • Statistics Line
  • Troubleshooting
  • Contributing
  • Author
  • License

asciidoctor-latexmath is an Asciidoctor extension that renders latexmath blocks and inline macros into static images. It leverages the LaTeX toolchain already installed on your system so you can produce consistent formulas in environments where MathJax or similar browser-side renderers are not an option.

• Offline-first rendering – no external services or JavaScript runtime required.
• LaTeX fidelity – relies on the same pdflatex, xelatex, or lualatex tooling used for high-quality print workflows.
• Multiple output formats – generate PDF, SVG, or PNG assets to match your target backend.
• Drop-in integration – register the extension once and keep authoring with the familiar latexmath syntax.
• Intelligent caching – reuse previously rendered block and inline formulas; cache hits skip the LaTeX toolchain entirely.

This extension assumes a trusted documentation source (version-controlled repository you control). Explicit output basenames (first positional block attribute) may include relative path segments including .. and can therefore write outside the images directory intentionally (spec FR-008/FR-009 under trust model FR-036). If you process untrusted / user‑supplied AsciiDoc:

1. Disable asciidoctor-latexmath for that pipeline; OR
2. Run in a container / chroot / sandbox restricting filesystem writes; OR
3. (Future) Enable the planned strict mode (will reject path traversal).

Shell escape is never enabled (FR-017). Cache key excludes engine & converter tool names/versions (P5 / FR-011); pin a single toolchain if you need identical byte output across environments.

1. The extension intercepts latexmath blocks and inline macros during the Asciidoctor conversion pipeline.
2. The captured TeX snippet is compiled with your preferred LaTeX engine (pdflatex, xelatex, lualatex, or tectonic) into a minimal standalone document.
3. The resulting PDF is post-processed into the requested target format (PDF/SVG/PNG).
4. The rendered asset is embedded back into the document output so it behaves like any other image.

All processing happens locally, which keeps your documentation builds reproducible and secure.

Make sure the following tools are available on your system PATH before enabling the extension:

• Ruby 3.3+ and Asciidoctor 2.0+
• A LaTeX engine such as pdflatex, xelatex, lualatex, or tectonic (provided by TeX Live, MiKTeX, MacTeX, etc.)
• Optional: dvisvgm for SVG conversion and ImageMagick or ghostscript for PNG conversion
• Computer Modern fonts (usually bundled with the TeX distribution)

You can verify pdflatex availability with:

pdflatex --version

Swap in another engine if that is your default workflow—for example, xelatex --version or tectonic --help.

gem install asciidoctor-latexmath

gem 'asciidoctor-latexmath'

Run bundle install to make the extension available to your project.

Clone this repository and point Asciidoctor at the local checkout:

git clone https://github.com/your-org/asciidoctor-latexmath.git
cd asciidoctor-latexmath
bundle install

Then require the extension via a relative path (see Quick Start).

Render a document with offline latexmath support:

asciidoctor -r asciidoctor-latexmath -a latexmath-format=svg sample.adoc

Select a different engine by providing the pdflatex attribute at runtime. For example, to build with tectonic:

asciidoctor -r asciidoctor-latexmath -a pdflatex=tectonic -a latexmath-format=svg sample.adoc

During development, load the registration file directly from your working tree:

asciidoctor -r ./lib/asciidoctor-latexmath.rb -a latexmath-format=svg sample.adoc

Sample AsciiDoc snippet:

The famous mass-energy equivalence equation is shown below.

[latexmath]
+++
E = mc^2
+++

Einstein also described spacetime curvature with the inline latexmath:[E_{\mu\nu} = 8 \pi T_{\mu\nu}] variant.

The extension replaces both expressions with rendered images that match the format specified in latexmath-format.

Deprecated alias: latexmath-cache-dir / cache-dir is still accepted (emits a one-time INFO log) but you should prefer latexmath-cachedir / cachedir.

The renderer always emits \documentclass[preview,border=2pt,<size>]{standalone}. The document attribute :latexmath-fontsize: sets the default size (12pt); blocks and inline macros can override it with fontsize= while still participating in caching. Values must end with pt—otherwise the extension raises Asciidoctor::Latexmath::UnsupportedValueError with an actionable hint.

:latexmath-fontsize: 10pt

[latexmath, fontsize=18pt]
+++
\int_a^b f(x)\,dx
+++

Inline macros support the same keyword attributes except for positional target=/format. Attributes follow asciidoctor-diagram precedence: element attribute → element options → document attribute → default.

Set attributes via the CLI (-a latexmath-format=png) or inside the document header. Positional attributes follow the asciidoctor-diagram convention: [latexmath, basename, format].

All generated images respect Asciidoctor's standard image directory rules. Use imagesoutdir to control the physical output location and imagesdir to influence how assets are referenced in HTML. Inline math inside literal table cells is also supported—the processor injects the rendered <span class="image math">…</span> markup automatically.

The renderer persists every successful compilation so repeated conversions can reuse the existing SVG/PNG/PDF payloads without invoking your LaTeX toolchain again. Cache entries hash the following ordered fields with SHA256: extension version, normalized content hash, output format, preamble hash, font-size hash, PPI (PNG only, otherwise -), and entry type (block | inline). Delimiter changes, engine switches, or tool swaps do not affect the cache key (FR-011 / P5), so switching pdflatex → xelatex with other factors constant reuses the same cache entry. Inline rendering via -a latexmath-inline reuses the cached inline markup; enabling -a data-uri does not invalidate cached images.

By default, cache files live under <outdir>/.asciidoctor/latexmath. Override this location with -a latexmath-cachedir=path/to/cache (legacy -a latexmath-cache-dir=... still works but logs a deprecation message) or disable caching altogether with -a latexmath-cache=false when you need a clean rebuild. Removing the cache directory forces the next run to regenerate every formula.

Rendered output keeps formulas accessible by emitting <img> elements with role="math", alt text set to the raw LaTeX snippet, and a data-latex-original attribute for tooling. Blocks inherit the usual Asciidoctor figure roles, while inline expressions blend into text content without breaking line height.

When logging at INFO (the default), the extension prints a single summary line per run:

latexmath stats: renders=<int> cache_hits=<int> avg_render_ms=<int> avg_hit_ms=<int>

Fields are fixed in name and order (FR-022 / FR-035). Use this line to monitor warm-cache behaviour in CI or to flag unexpected cache misses.

Choose asciidoctor-latexmath when you already depend on a LaTeX distribution and want fully offline builds with minimal additional dependencies.

• LaTeX engine not found – install a LaTeX distribution (TeX Live, MiKTeX, MacTeX, or Tectonic) and ensure the binaries are on your PATH.
• Blank or clipped formulas – enable -a latexmath-keep-artifacts=true and inspect the generated .log file for LaTeX errors.
• Missing glyphs – install Computer Modern or other math-capable fonts that ship with TeX Live/MacTeX.
• Slow builds – caching is enabled by default; ensure <outdir>/.asciidoctor/latexmath is writable. Use -a latexmath-cache=false if you need to force a full regeneration.

Bug reports, feature requests, and patches are welcome. Please open an issue describing the use case before submitting large changes. If you plan to contribute code, follow the established Ruby style guidelines and add documentation or samples for new behaviors.

Created and maintained by Shuai Zhang.

Licensed under the LGPL-3.0-or-later WITH LGPL-3.0-linking-exception. See LICENSE for the full text.