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.

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

---

Requirements (mermaid)

Item	Requirement
TeX engine	upLaTeX / pdfLaTeX / XeLaTeX / 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

With upLaTeX + dvipdfmx, specify the dvipdfmx option, e.g. \documentclass[dvipdfmx]{article}.

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

Using \mermaidfile

The \mermaidfile[<includegraphics options>]{filename} command renders Mermaid source from an external .mmd file and includes the resulting PDF. This works with both mermaid and ltmermaid.

\documentclass{article}
\usepackage{ltmermaid} % or mermaid

\begin{document}
\mermaidfile[width=0.8\linewidth]{diagram-001.mmd}
\end{document}

The optional argument is forwarded directly to \includegraphics, so any valid graphics key is accepted, such as width, height, angle, trim, or keepaspectratio.

You can also pass local options to the inline environment:

\begin{mermaid}[width=0.8\linewidth]
flowchart LR
  A --> B
\end{mermaid}

---

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 -f when it is passed).
\MermaidPdfFit	Always passes -f (--pdfFit) to the renderer.
\MermaidNoPdfFit	Never passes -f (--pdfFit) to the renderer.
\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.

By default, -f is passed only when <renderer> --version reports Mermaid CLI 11 or older (Mermaid CLI 12 removed -f). If the version cannot be detected, -f is not passed; add \MermaidPdfFit if you use Mermaid CLI 11 or older.

---

Output Files

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. When -output-directory is used (e.g. latexmk -outdir=build), they are placed in $TEXMF_OUTPUT_DIRECTORY/mermaid/ with both packages.

A diagram is rendered only when its source or the renderer settings (Renderer, \MermaidRendererOptions, \MermaidPdfFit / \MermaidNoPdfFit) have changed since the last rendering. To render all diagrams again, delete the mermaid/ directory.

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

---

Revision History

mermaid.sty

• Version 1.1 (2026-10-22): Supported Mermaid CLI 12 (-f is passed only for Mermaid CLI 11 or older; added \MermaidPdfFit), rendered diagrams only when their source or renderer settings change, and supported -output-directory.
• Version 1.0c (2026-05-06): Various bug fixes.
• Version 1.0b (2026-04-29): Added \mermaidfile support, Makefile build/test targets, and l3build regression testing.
• Version 1.0a (2026-04-20): Renamed sample documents.
• Version 1.0 (2026-04-16): Stable release.

ltmermaid.sty

• Version 1.1 (2026-10-22): Supported Mermaid CLI 12 (-f is passed only for Mermaid CLI 11 or older; added \MermaidPdfFit), rendered diagrams only when their source or renderer settings change, and fixed output file name conflicts between the mermaid environment and \mermaidfile.
• Version 1.0c (2026-05-06): Various bug fixes.
• Version 1.0b (2026-04-29): Added \mermaidfile support, Makefile build/test targets, and l3build regression testing.
• Version 1.0a (2026-04-20): Renamed sample documents.
• 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.

---