Mermaid in Emacs: Preview Markdown and Compile Diagrams

Emacs can edit Mermaid source and compile it to an image with mermaid-mode and the Mermaid CLI. For a complete Markdown document, markdown-mode provides preview commands, but the chosen Markdown renderer must also support Mermaid. Installing an editing mode alone does not add a diagram renderer to HTML output.

Choose the workflow based on your input: a standalone .mmd diagram, or a .md file containing prose and fenced diagrams.

Compile a Standalone Mermaid Diagram

Install the official Mermaid CLI in a terminal with Node.js and npm available:

npm install -g @mermaid-js/mermaid-cli
mmdc --help

In Emacs, install mermaid-mode with M-x package-install RET mermaid-mode RET. The package is available through MELPA; configure that archive first if your package list does not include it. Refresh the package list with M-x package-refresh-contents after configuring the archive.

Save this source as workflow.mmd, without Markdown backtick fences:

graph LR
  Draft[Draft] --> Review[Review]
  Review --> Publish[Publish]

Open the file, enable M-x mermaid-mode if it is not selected automatically, and press C-c C-c. The mode runs the compiler and opens the resulting image in an Emacs buffer. PNG is its default output format.

For a separate SVG asset, run this in your terminal:

mmdc -i workflow.mmd -o workflow.svg

Use the generated image in documentation that accepts image files. Keep workflow.mmd as the editable source.

Fix an Emacs PATH Problem

If mmdc --help works in your shell but compilation fails in Emacs, compare the executable lookup inside Emacs:

(executable-find "mmdc")

Evaluate that expression with M-:. A nil result means Emacs cannot find the compiler. This can happen when a GUI application starts with a different environment from your terminal.

Either correct Emacs's environment or configure mermaid-mmdc-location to the absolute executable path on your machine. Use command -v mmdc in a POSIX shell to find that path. Avoid copying a path from someone else's Node.js installation.

If the executable is found but compilation still fails, run the SVG command above on the same file. Compiler errors or missing browser dependencies need to be resolved before editor shortcuts can work reliably.

Preview a Markdown Document in Emacs

Install markdown-mode, open your .md file, and check the configured markdown-command. That command is the external processor used to turn Markdown into HTML.

In markdown-mode, C-c C-c p previews the generated HTML in a browser. Start with a heading and a paragraph to confirm that ordinary preview works. Then add a fenced Mermaid block:

```mermaid
graph LR
  Source --> Preview
```

If the browser shows that block as code, the HTML pipeline has not rendered Mermaid. Reinstalling the editing mode will not by itself change the renderer's capabilities. Use a renderer configured for Mermaid, or save the document and open it in mdview.io to check the complete file.

Common Preview Failures

What you see	Next step
Package not found	Verify the package archive and refresh its contents.
Compiler cannot be started	Check executable-find and the compiler location.
Parse error for a .mmd file	Remove Markdown fences and test the three-node example.
Markdown preview shows Mermaid source	Check whether the HTML renderer supports Mermaid.
One renderer accepts the diagram and another rejects it	Compare their Mermaid versions and reduce the failing example.

For a repeatable export outside Emacs, follow rendering Mermaid with the CLI. For editor comparisons, see the Markdown and Mermaid editor overview.