Trust and Meaning: Security and Accessibility at the SVG Boundary

Mermaid’s visual layer determines what readers see, but the SVG boundary determines what a host is willing to expose and who can understand it. This chapter examines two responsibilities that meet at that boundary: controlling what diagram text can do in a browser, and carrying enough meaning into the SVG for people who do not perceive the picture visually. The practical judgment is not whether Mermaid is simply “safe” or “accessible,” but which protections a deployment needs and which work remains with the site owner and diagram author.

The tension begins with the same feature that makes Mermaid expressive. Labels, titles, links, and other text are useful because they can carry information and sometimes interaction. They also contain characters and structures that have meaning to HTML and browsers. A diagram definition is still input to a rendering pipeline, even when it appears inside a documentation page.

Why labels become a trust boundary

Mermaid’s repository describes a public-site risk: user-controlled content may be stored and later presented in a browser, while diagram syntax contains many characters used by HTML. Ordinary sanitization can break a diagram if it removes everything that looks like markup. The result is a genuine design tension. The renderer must preserve enough expressive content to make diagrams useful while preventing diagram text from becoming an unintended script or page-level instruction.

That is why Mermaid exposes a securityLevel rather than one universal behavior. The levels express different assumptions about the source and different tolerances for lost interaction.

With strict, the documented default, HTML tags in text are encoded and click functionality is disabled. This is the conservative posture for a host that does not want diagram authors to control active content or interactions. It favors predictable isolation over rich labels. A definition can still communicate a relationship, but a feature that depends on HTML or clicks may no longer work as the author expects.

With antiscript, HTML in text is allowed while script elements are removed, and click behavior is enabled. This mode narrows one threat without making the output as restrictive as strict mode. Its name should not be read as a universal safety guarantee: removing script elements does not make every surrounding integration decision irrelevant, and Mermaid’s own documentation places responsibility on the site owner to distinguish trusted from untrusted sources.

With loose, HTML tags and click functionality are allowed. This can be useful when diagram authors are trusted and the page needs richer interaction, but it also makes the trust assumption explicit. The rendering path does not apply the same final SVG sanitization used at stricter levels. A site that selects loose behavior is choosing capability in exchange for a larger responsibility to control the source and the surrounding page.

With sandbox, rendering takes place in a sandboxed iframe. The aim is to prevent JavaScript in the diagram from running in the surrounding context. The cost is functional: sandboxing can hinder scripts, popups, links to other targets, and other interactions that depend on normal page context.