mermaid-filter: rendering mermaid diagrams through Pandoc

Mermaid blocks that survive a Pandoc build

Mermaid diagrams live inside markdown as text, which is convenient right up to the moment someone has to build the document. Without help, Pandoc treats a mermaid code block as a literal code listing, and the diagram exists only in the source. mermaid-filter is a Pandoc filter that closes that gap by adding support for mermaid syntax diagrams in markdown.

The authoring experience is deliberately unobtrusive. You write the diagram the way you already write mermaid, in a fenced code block marked as mermaid, holding a sequence diagram with two messages in it. During the build, the filter finds those blocks, hands the diagram source to mermaid-cli, and substitutes the rendered result into the output document as an image reference. The reader gets a picture, the author keeps a text diagram in version control, and the diagram stays diffable.

The audience is technical writers and documentation teams whose toolchain already runs Pandoc. If you do not build with Pandoc, this filter has no place in your workflow, and if you want diagrams generated by a hosted service rather than a local renderer, the overhead here is real.

A thin wrapper around mermaid-cli and Puppeteer

The package manifest makes the architecture plain. mermaid-filter is a Node program whose entry point is index.js, and the dependencies list @mermaid-js/mermaid-cli at a major version 11, pandoc-filter, imgur, minimist, sanitize-filename and tmp. The library directory holds the rest of the implementation.

The important dependency is mermaid-cli, because mermaid-filter does not draw diagrams itself. It locates mermaid blocks, calls the mermaid command line tool, and takes the output file it produced. That is why the option table maps so directly onto mermaid.cli flags: the theme option corresponds to the --theme flag, the background option corresponds to --backgroundColor, and the Puppeteer configuration file is passed through the -p option of mmdc.

The consequence is that the filter inherits mermaid-cli's weight. mermaid-cli renders with a headless browser, which is where Puppeteer enters the picture, and the filter also ships a .puppeteer.json pass-through so you can point the renderer at your own browser setup. A build that installs this filter also installs a browser toolchain. That is the price of server-side mermaid rendering, and it is worth sizing before you commit a CI pipeline to it.

The repository layout also shows a test.sh wired as the e2e script with jest as the unit test runner, plus a test.md fixture, which is a sign of how the project verified that blocks were picked up and replaced.

Installing the filter and running it with Pandoc

Installation is a global npm install, and the filter is then named on the Pandoc command line with the -F flag:

npm install --global mermaid-filter

To convert a markdown file to HTML, the documented command is:

pandoc -t html -F mermaid-filter -o something.html something.md

The -F flag is what registers the filter, and -t html selects the output format. After running it, the mermaid blocks in something.md should appear as images in something.html rather than as code listings.

Windows needs one adjustment. The documentation notes that on Windows you need mermaid-filter.cmd in the command line instead, because the global install places a command shim there. There is a further wrinkle for Windows 8.1, where mermaid-filter.cmd fails apparently because of a change in how CMD.exe works for subprocesses, a problem the project links to an issue thread about. The workaround is to edit the globally installed mermaid-filter.cmd in the user profile AppData Roaming npm directory to use ~dp$PATH:0, and you have to repeat this after every install or update because the package overwrites the cmd file.

That is the kind of detail that decides whether this tool works for you, and it is worth checking your platform before anything else.

Attribute syntax, and why the class has to be there

Per-diagram control is done through Pandoc attributes on the fenced code block, and the requirement is specific: to use options in attributes you need the curly braces syntax with the .mermaid class attached. The project is candid that this is uglier than the earlier syntax, but explains that it is how Pandoc wants it. The attribute form attaches the class and the option to the fence, in curly braces, with the .mermaid class first and loc=img as the option.

The loc=img value here saves the generated diagram into the img subfolder of the current working directory, rather than inlining it.

The reason for the class requirement is how Pandoc distinguishes a code block from a diagram block. Without the .mermaid class the filter has no way to know a block is meant for it, so a bare mermaid fence is left as an ordinary code block.

A second attribute form adds an identifier, which is what makes the images referenceable. The block gets an id such as fig:example, and a document can then refer to the diagram with a matching @fig:example reference that gets inserted automatically. The title attribute is set to fig: when the identifier starts with fig:. The project points at pandoc-crossref for this pattern and warns about filter order: mermaid-filter has to be applied before pandoc-crossref, so that crossref can find the images the filter produced.

Nine options, with environment variables for CI

The option table is the practical reference for the tool, and each row pairs a name, a default and an environment variable. The caption option sets the alt attribute on the image and has no default. The format option defaults to png and allows svg. The width option defaults to 800. The theme option defaults to the mermaid default and corresponds to the --theme flag of mermaid.cli, and the background option defaults to white and corresponds to --backgroundColor.

The filename option has no default and takes precedence when set. The loc option defaults to inline, which generates a data url, and also allows imgur to upload to imgur, with any other value saving images to a folder of that name. The scale option defaults to 1, and imageclass has no default and sets a class on the generated image.

Every one of these has a MERMAID_FILTER_ prefixed environment variable, which is the part that makes the filter usable in a build pipeline. A CI job can set MERMAID_FILTER_FORMAT and MERMAID_FILTER_WIDTH without rewriting the markdown, and a documentation site can force MERMAID_FILTER_LOC to a folder so the image files land somewhere the site build can pick up.

The imgur option deserves a second look. It uploads a rendered diagram to a public image host, so a diagram in a private or embargoed document ends up on a third-party service. The default of inline avoids that entirely, and the local folder option is the better choice for internal documentation.

Local configuration files picked up from the working directory

Beyond per-diagram attributes, the filter reads three configuration files from the current working directory if they exist. Mermaid cli accepts extra options in a JSON configuration file and a CSS file, so mermaid-filter looks for .mermaid-config.json and .mermaid.css and passes them through when found. Separately, it looks for .puppeteer.json and passes that to mermaid cli through the -p option of mmdc.

This is a quiet but significant behaviour, because the files are picked up implicitly from wherever the build happens to run. A repository that carries a .mermaid-config.json changes the rendering of every diagram in the build, with no change to the markdown. The same goes for a .mermaid.css, which is how you restyle a diagram consistently across a documentation set, and for a .puppeteer.json, which is how you point the renderer at a browser binary when the bundled download is not an option in your environment.

The flip side is that behaviour can differ between a developer machine and a CI runner purely because one of them has those files present. If diagrams look different in CI than they do locally, these three files are the first thing to check.

The project does not document a way to disable the lookup, so the practical approach is to keep the configuration files in the repository root alongside the markdown and treat them as part of the build contract.

A dependency that outgrew the filter

The release history tells a clear story about where the risk sits. The versions are v1.4.5 in October 2020, described as a bug fix for a file handle leak plus support for the mermaid fit flag, v1.4.6 in March 2022, and v1.4.7 in December 2023 with a note of minor updates. The last push to the repository was on 2026-04-16.

So the filter itself has been quiet for a while, and the last release predates the mermaid-cli major version it now depends on. The package.json pins @mermaid-js/mermaid-cli at ^11, which is a range that will keep pulling the newest 11.x release. That is a deliberate choice for security patches, but it also means the CLI underneath can change shape without the filter changing, since the filter sits on the same repository and follows upstream.

This is the case where the filter is the wrong tool. If your documentation build needs mermaid rendering to be stable and pinned, and you cannot accept a moving dependency or a Chromium download in every build, then a pre-render step where you run mermaid-cli yourself, commit or cache the SVG output, and let the markdown reference image files is the more controlled arrangement. It gives up the single-command convenience and gains reproducibility.

The package is declared BSD-2-Clause in the manifest, which is a permissive licence with no copyleft obligation on anyone embedding the filter. The project licence field is the one recorded in the package itself, and the repository root listing shows a LICENSE file.

Editorial conclusion

Adopt mermaid-filter if your documentation is written in markdown, built with Pandoc, and needs mermaid diagrams without hand-rendering each one. Do not adopt it expecting active upstream development, since the last release was v1.4.7 in 2023 and the last push was on 2026-04-16, and do not reach for it if you would rather not ship a Puppeteer-based Chromium in your build. Verify first that the mermaid-cli version your build pulls in still accepts the -p, --theme and --backgroundColor flags the filter passes, because that dependency sits outside this repository.

Frequently asked questions

Official sources

1. Issues
2. raghur/mermaid-filter on GitHub
3. README
4. Releases