Embed mermaid code within SVG

[sumau]

Feature request

Embed the original Mermaid source code inside generated SVG files, so that an SVG exported from Mermaid can be re-opened and edited by Mermaid-compatible editors.

This would allow a Mermaid diagram to be used as a portable, self-contained artifact: rendered visually as an SVG, but still containing the editable Mermaid source that produced it.

Problem

Mermaid diagrams are easy to author in Markdown, but difficult to reuse reliably across multiple locations.

Today, if the same diagram is needed in several places — for example a root README, documentation pages, package READMEs, or different repositories — teams generally have to choose between imperfect options.

1. Copy/paste the Mermaid source

The same fenced Mermaid block can be duplicated across multiple Markdown files.

For example:

flowchart TD
  A --> B

Loading

This gives every location an editable diagram, but there is no single source of truth. Over time, copies inevitably drift apart.

This is especially painful for organisations that maintain canonical architecture, platform, or workflow diagrams which need to be referenced from many service repositories. This is the kind of use case described in mermaid-js/mermaid#1944, where teams want to reference Mermaid diagrams across repositories.

However, Mermaid itself cannot fully solve this at render time because Markdown rendering is controlled by the host platform, such as GitHub, GitLab, npm, documentation sites, package registries, and so on.

2. Pre-render Mermaid diagrams to SVG

The practical workaround is to compile Mermaid diagrams to SVG using CI, usually with mermaid-cli, and commit the rendered images.

This allows the SVG to be referenced from multiple Markdown files or even across repositories using a raw URL.

For example:

https://raw.githubusercontent.com/org/docs/main/diagrams/architecture.svg

This works, but it creates a new problem: the SVG becomes a build artifact separate from the Mermaid source.

That means:

• the diagram source and rendered output can get out of sync;
• contributors may edit the .mmd file but forget to regenerate the SVG;
• reviewers have to check both the source and generated artifact;
• repositories contain duplicated representations of the same diagram;
• the SVG is not easily editable unless the original Mermaid file is also found.

3. Encode the diagram into a Mermaid Live / mermaid.ink URL

Another workaround is to encode the Mermaid source into a Mermaid Live or mermaid.ink URL.

This avoids committing a generated build artifact, but it moves the source out of the repository and into a long, unreadable encoded URL. That makes diagrams harder to review, diff, maintain, and govern in normal source-control workflows.

Proposed behaviour

When Mermaid exports or renders a diagram to SVG, it should optionally embed the original Mermaid source code inside the SVG metadata.

For example, the SVG could contain the Mermaid source in a metadata element, data attribute, comment, or similarly discoverable structure.

Conceptually:

<svg>
  <metadata>
    <mermaid>
      flowchart TD
        A --> B
    </mermaid>
  </metadata>

  <!-- rendered SVG content -->
</svg>

This would make the SVG a self-contained Mermaid artifact:

• the SVG can be referenced anywhere images are supported;
• the diagram remains visually renderable without special Mermaid support;
• Mermaid-aware editors can re-open the SVG and recover the original source;
• the embedded source remains available even if the standalone .mmd file is not present;
• the SVG can act as both the rendered image and the editable diagram file.

This is similar in spirit to Excalidraw’s embedded scene data feature, where an exported image can contain the underlying editable scene data, and has proved really popular with developers.

Why this is useful

Embedding Mermaid source in SVG would provide a portable source-of-truth model for Mermaid diagrams.

It would help in cases where Mermaid diagrams need to be reused outside a single Markdown file or repository, including:

• GitHub READMEs;
• documentation sites;
• npm/package registry pages;
• monorepos;
• service repositories;
• internal developer portals;
• external documentation;
• systems that support SVG images but do not natively render Mermaid.

I have also raised a related GitHub Community discussion requesting support for rendering Mermaid diagrams that are referenced from .mmd or .mermaid files:

https://github.com/orgs/community/discussions/201064

That would improve reuse within GitHub-hosted Markdown. However, embedding Mermaid source inside SVG would solve a broader portability problem, because the resulting SVG could be used anywhere SVG images are accepted — not just inside GitHub.

Example workflow

A team maintains a canonical architecture diagram:

docs/architecture.svg

The SVG is referenced from multiple places:

https://raw.githubusercontent.com/org/docs/main/architecture.svg

A contributor opens architecture.svg in a Mermaid-aware editor.

The editor detects embedded Mermaid source, extracts it, and presents the original Mermaid code for editing.

When the contributor saves, the editor updates both:

1. the rendered SVG content; and
2. the embedded Mermaid source.

The SVG remains directly usable as an image, while also preserving the editable Mermaid source inside the file.

Who benefits

This would benefit:

• organisations that maintain canonical architecture or system diagrams in a central documentation repository;
• teams that need to reference the same diagram from many service repositories;
• monorepos where multiple package READMEs share common diagrams;
• documentation teams that publish the same diagram across different platforms;
• maintainers who want diagram changes to remain reviewable and source-controlled;
• non-technical contributors who want to edit a diagram without needing to locate a separate source file;
• tool authors building Mermaid-compatible editors, previewers, and documentation workflows.

Expected outcome

Mermaid-generated SVGs should optionally preserve the source Mermaid definition used to create them.

This would make SVG exports more useful as durable, portable, and editable diagram artifacts. It would reduce duplication and drift, while improving reuse across Markdown files, repositories, documentation systems, package ecosystems, and other platforms that support SVG images.