LaTeX Packages to Embed Mermaid Diagrams (mermaid / ltmermaid)

Embed Mermaid diagrams in LaTeX. Diagram sources are written to disk, and the Mermaid CLI (mmdc) renders vector PDFs, which are then included using \includegraphics.

Originally, ltmermaid was created exclusively for LuaLaTeX. Subsequently, the mermaid package was developed as a LuaTeX-independent version to support other engines. Therefore, there are two packages provided in this repository:

• mermaid.sty (mermaid)

The implementation to be used with pdfLaTeX / XeLaTeX / upLaTeX / LuaLaTeX, etc. It invokes the Mermaid CLI via the shellesc package (or directly via \write18). No Lua interpreter is required.

• ltmermaid.sty (ltmermaid)

An implementation dedicated to LuaLaTeX that provides the same macros (the Renderer option, \Mermaid... macros, and the mermaid environment) as the mermaid package above. The CLI is invoked via Lua's os.execute, and the package handles LuaLaTeX-specific behavior such as outputting to mermaid/ under -output-directory / TEXMF_OUTPUT_DIRECTORY.

Both packages can be chosen when using lualatex. The distinction is that you use mermaid when you want to use Mermaid with an engine other than Lua, and ltmermaid when you prefer a LuaLaTeX-native implementation and output-directory coordination.

Author: Ryoya Ando — https://ryoya9826.github.io/ License: LPPL version 1.3c Source & issues: https://github.com/ryoya9826/ltMermaid

---

Requirements (mermaid)

Item	Requirement
TeX engine	upLaTeX / pdfLaTeX / LuaLaTeX, etc. (Lua interpreter is not required)
LaTeX format	LaTeX2ε
Shell escape	-shell-escape (the CLI is invoked via shellesc / \write18)
External tool	Mermaid CLI (mmdc)

If the CLI is missing in the environment, this package does not install it automatically. If you pass a command containing npx -y (e.g., npx -y @mermaid-js/mermaid-cli) to Renderer, npx may download the package. Unless another command is specified via Renderer, mmdc must be on the PATH in the compilation environment. Headless Chromium (Puppeteer) is required. Please refer to the Mermaid CLI documentation for details.

For ltmermaid

The following points differ from mermaid:

Item	Requirement
TeX engine	LuaLaTeX (lualatex) only
Shell escape	lualatex -shell-escape (the CLI is invoked via os.execute)

As stated above, the engine is limited to LuaLaTeX. In other respects, the handling of external tools and Renderer / npx is identical to mermaid.

---

Usage (Minimal Example)

For mermaid

\documentclass{article}
% Example if `mmdc` is not on PATH:
% \usepackage[Renderer={npx -y @mermaid-js/mermaid-cli}]{mermaid}
\usepackage{mermaid}

\begin{document}
% Optional: cap width at 80\% of line; small diagrams aren't scaled up
% \MermaidAdjustBoxOpts{max width=0.8\linewidth,center}
% \MermaidAdjustBoxOpts{max width=0.9\linewidth,center,valign=T}

\begin{mermaid}
flowchart LR
  A --> B
\end{mermaid}
\end{document}

Compilation examples:

pdflatex -shell-escape yourfile.tex
xelatex  -shell-escape yourfile.tex
lualatex -shell-escape yourfile.tex
uplatex -shell-escape yourfile.tex && dvipdfmx yourfile.dvi

For ltmermaid

Change the package name to ltmermaid (the mermaid environment in the body remains the same).

\documentclass{article}
% \usepackage[Renderer={npx -y @mermaid-js/mermaid-cli}]{ltmermaid}
\usepackage{ltmermaid}

\begin{document}
\begin{mermaid}
flowchart LR
  A --> B
\end{mermaid}
\end{document}

Compilation is only possible with LuaLaTeX:

lualatex -shell-escape yourfile.tex

---

Renderer and Macros

Whether using mermaid or ltmermaid, the following specification methods are the same (just substitute the package name in \usepackage).

Mechanism	Purpose
\usepackage[Renderer=...]{mermaid}, etc.	The prefix of the execution command line. The default is mmdc if omitted.
\MermaidRendererOptions{...}	Extra CLI arguments passed before -i / -o (merged after the default -f).
\MermaidNoPdfFit	Disables the -f (--pdfFit) option for mmdc (default is enabled).
\MermaidAdjustBoxOpts{...}	Additional options for the adjustbox environment used for diagram placement (default is max width=0.9\linewidth,center).
\MermaidGraphicsOpts{...}	Extra options passed to \includegraphics (e.g. angle or trim). The width is typically adjusted with \MermaidAdjustBoxOpts.

---

Output Files

For mermaid

Intermediate .mmd and .pdf files are output to the mermaid/ directory right under the compilation directory. The file names will be a concatenation of the job name and a sequential number, such as \jobname-mermaid-1.mmd. This does not follow -output-directory / TEXMF_OUTPUT_DIRECTORY.

For ltmermaid

They are basically output to mermaid/ in the same way, but when -output-directory is used, they are placed in $TEXMF_OUTPUT_DIRECTORY/mermaid/.

For full explanations and diagram examples, see mermaid-sample.tex / mermaid-sample-ja.tex (mermaid) and ltmermaid-sample.tex / ltmermaid-sample-ja.tex (ltmermaid).

---

Revision History

mermaid.sty

• Version 1.0 (2026-04-16): Stable release.

ltmermaid.sty

• Version 1.0 (2026-04-16): Stable release.
• Version 0.2 (2026-04-13): Removed MERMAID_MMDC and MERMAID_MMDC_OPTIONS.
• Version 0.1 (2026-04-08): Initial release.

---