Exporting images.

Text output is the default because it reviews well and every host draws it. When you need a picture instead, --format=svg and --format=png render one through a locally installed mermaid-cli.

npm i -D @mermaid-js/mermaid-cli
php artisan cartographer:erd --format=svg

   INFO  Generated 9 entities and 18 edges. Written to [/srv/blog/docs/erd.svg].

mermaid-cli is not a dependency

The package never installs a renderer. It shells out to one you already have, and an export either finds a binary or fails saying how to get one. That keeps composer require --dev byrcsc/laravel-cartographer free of node, a headless browser, and a Mermaid build, none of which a Markdown run needs.

Three locations are searched, in order:

mmdc, mmdc.cmd, and mmdc.exe are all recognised, so an npm install on Windows resolves the same way.

Setting export.mermaid_cli stops the search rather than adding to it. A configured path that does not exist or is not executable fails immediately, instead of silently falling through to a different binary than the one you named:

   ERROR  The mermaid-cli binary configured at [/opt/mmdc] is missing or not
          executable. Correct [cartographer.export.mermaid_cli], or remove it
          to search the project and PATH.

With nothing configured and nothing found:

   ERROR  No mermaid-cli binary was found in [node_modules/.bin/mmdc] or on
          PATH. Install it with [npm i -D @mermaid-js/mermaid-cli], or point
          [cartographer.export.mermaid_cli] at the binary.

An export writes two files

php artisan cartographer:erd --format=svg --output=docs/erd.md

docs/erd.svg        the rendered diagram
docs/erd.svg.mmd    the Mermaid source it came from

Two things happen to the path. The extension is replaced with the format, so pointing --format=svg at the default docs/erd.md cannot leave image bytes in a file named .md. Then the source is written beside the image, at the image path plus .mmd.

The source file is not a convenience. It is what cartographer:check compares, and the next section is why.

Why a check compares the source, not the image

mermaid-cli output is not byte-stable between its own versions. The same diagram rendered by two releases differs in generated identifiers, spacing, and sometimes layout, none of which reflect a change to your schema.

If the check compared the image, every renderer upgrade would report every diagram as stale, and the signal would be gone within a release or two. Comparing the .mmd beside it fixes that: the source moves only when your models or your schema move, which is the thing the check exists to catch.

The consequence is worth stating plainly. cartographer:check never runs mermaid-cli, so a CI job that verifies an exported diagram needs no node and no browser. Only the job that regenerates one does.

- name: Check the ERD is current
  run: php artisan cartographer:check # no node needed

Commit both files. The .mmd is what makes the image checkable, and dropping it turns the check into a permanent "missing" failure.

Size limits do not apply to an export

Cartographer supplies the renderer configuration for an export and raises maxTextSize and maxEdges far past anything a schema produces. An export therefore succeeds on diagrams GitHub refuses to draw, and no size warning is printed for one.

This is the escape hatch when a diagram is too big for a hosted renderer and splitting it into groups is not what you want.

Under --stdout

php artisan cartographer:erd --format=svg --stdout > diagram.svg

--stdout writes the rendered artifact to the stream and no source file, so it is for one-off piping rather than for something you commit. A file you intend to check needs the .mmd beside it, which means writing it normally.

When the render fails

The exporter runs mermaid-cli in a temporary directory and reports what it said. A non-zero exit is passed through with the renderer's own output attached:

   ERROR  mermaid-cli failed to render the png diagram (exit code 1).
          Error: Failed to launch the browser process

That class of message is a mermaid-cli or Puppeteer problem rather than a Cartographer one, and it reproduces outside the package:

npx -y @mermaid-js/mermaid-cli -i docs/erd.svg.mmd -o /tmp/erd.svg

A render that hangs is stopped after five minutes:

   ERROR  mermaid-cli did not finish within 300 seconds. Raise the limit by
          rendering fewer entities, or check that the binary at
          [/srv/blog/node_modules/.bin/mmdc] works.

On a diagram large enough to reach that, --columns=keys or a group is a better answer than a longer wait.

Choosing between svg and png

Prefer svg where you have the choice. A large ERD in PNG is either unreadable or enormous, and text in an SVG stays selectable and searchable.

Fonts are the one place they differ in kind. An SVG references a whole font stack and the viewer falls through it; a PNG rasterizes with whatever fonts the rendering machine has. See themes and fonts.

Should you commit the image?

Committing text is the default recommendation for a reason: a Markdown diagram diffs, and the diff is most of the value. An image does not diff, so a committed PNG tells a reviewer that something changed and nothing about what.

Export when you need a picture for a place that cannot render Mermaid, and keep the Markdown diagram as the reviewable artifact. If you do commit an image, commit its .mmd too and let cartographer:check cover both.

What to read next

• Themes and fonts for the presets an export can be drawn in.
• Renderer limits for what an export lets you sidestep.
• Continuous integration for checking an exported diagram without a renderer.