Will Your Mermaid Diagrams Work in Pele? Five Checks Before Switching
Checked 18 October 2026. Pele understands Mermaid diagram syntax, but that does not mean it produces the same picture or preserves every interactive feature. Before switching a documentation site or testing an upcoming Obsidian integration, check appearance, behavior and external resources separately.
This is a source-based migration checklist, not a hands-on benchmark. We have not tested your vault, plugins or website.
What is actually available?
Pele is an open-source SVG rendering library developed for Obsidian. Its project describes support for the built-in diagram types in Mermaid 12.1.0. The developer’s public demo describes integration in the next Obsidian version, 1.15. That announcement is not proof that your installed app already includes it. The public changelog we checked still leads with the October 5 version 1.14 releases.
Use the standalone playground to evaluate non-confidential examples, or check your installed app’s release notes. Do not install an unrelated community plugin simply because its name includes Mermaid.
Sources: pele.run, GitHub repository, Obsidian changelog, Reddit announcement
1. Separate accepted syntax from identical appearance
Pele has its own layout engine. Expect different positions, spacing and connector paths even when the source parses. Its compatibility page excludes external Mermaid plugins such as ZenUML, ignores JavaScript click callbacks and does not support arbitrary HTML labels. Ordinary link-opening click statements are a different case and are supported.
Choose one representative diagram for each feature you actually use. A successful simple flowchart cannot certify a complex diagram, an external plugin or a callback-driven workflow. If exact placement carries meaning, keep a reference image and check it manually.
Source: Pele compatibility documentation
2. Review meaning carried by color
Mermaid theme settings are not a direct substitute for Pele’s CSS variables. The compatibility documentation says Mermaid themeVariables colors do not apply. Pele’s theming guide also distinguishes theme-aware colors from colors fixed inside the diagram.
This matters when red means failure, green means approval or a particular color identifies an owner. A prettier chart can still communicate the wrong thing if that distinction disappears. Check both light and dark themes, including text against each node’s fill. Record the intended meaning in words so color is not the only way to understand it.
Sources: compatibility and theming guides
3. Check narrow layouts instead of shrinking your desktop screenshot
Pele’s API distinguishes rendering an SVG string with render() from mounting an adaptive diagram with mount(). With a supplied container width, supported layouts can change direction below the documented default breakpoint of 640 pixels. That is an available library behavior, not a promise about every host application.
Test the same diagram in a narrow reading pane and at your normal desktop width. Check whether the process still reads in the right order, whether labels remain legible and whether connections cross in a confusing way. Developers embedding Pele can review autoDirection, maxWidth and responsive options rather than assuming every chart will fit automatically.
Source: Pele API documentation
4. Do not confuse local rendering with “nothing can contact the internet”
A renderer working without a cloud rendering service does not certify the whole page as offline. Pele’s security documentation explicitly warns that displayed images can make network requests. It documents options to disable links and images; the hosting application decides how those controls are used.
For private diagrams, check linked images and the host application’s policies. Do not upload confidential source to a public playground as a test. We have not audited Obsidian’s future integration or measured its network traffic, so this article does not claim it sends diagram text to a server—or that every configuration is network-free.
Source: Pele security documentation
5. Keep a small acceptance record before a broad change
Make a review sheet with five columns: diagram name, feature used, expected meaning, observed result and follow-up owner. Mark results as not tested until someone checks them. Keep the original source and a known-good reference, and test a copy before changing an important shared document.
A useful acceptance rule is simple: proceed when the diagrams you depend on remain understandable and their required links work in the actual target app. Pause when a necessary feature is unsupported or behavior is still unknown. Speed claims should not override that decision. Any performance figures on the project website are developer claims, not our independent measurements.
Knowledge check: two migration traps
Pele Migration: Two Checks
Question 1: If a diagram parses, must its colors, positions and callbacks match Mermaid? No. Parsing and behavioral equivalence are separate checks.
Question 2: Does local diagram rendering guarantee that displayed remote images make no network requests? No. External resources and host policies need their own review.
The embedded quiz checks these two distinctions only. It is not a compatibility scanner, does not inspect your files and does not report shared participant totals.
Bottom line
Treat Pele as a new rendering path, not an automatic certificate for every existing diagram. Start with a small, representative set, preserve your original source, and verify the behaviors that matter to your readers. For differences from Mermaid 12.1.0 syntax, the project recommends its comparison playground and issue-reporting process.
Primary references, checked 18 October 2026
