Pele: The Open-Source Tool That Turns Mermaid Diagrams into Themeable SVGs

Mermaid has become one of the de facto standards for developers drawing flowcharts, sequence diagrams, and architecture diagrams, but its built-in rendering styles often clash with product interfaces or documentation themes. The open-source project Pele, which recently appeared on Hacker News, targets exactly this pain point—outputting Mermaid diagrams as themeable SVG files.

What Is Pele

Pele is a tool that converts Mermaid diagrams into themeable SVGs. Traditional Mermaid rendering usually generates SVGs with inline styles directly, where colors, fonts, backgrounds, and the like are hard-coded into the graphic. To adapt to dark mode or brand color schemes, you often have no choice but to modify Mermaid's theme variables or replace colors with a script after the fact. Pele's approach is to extract styles from the graphic structure, giving SVGs themeability so the same diagram can be reused across different interfaces and documentation styles.

According to the discussion on Hacker News, the project received 27 points. Comments were few, but attention centered on recognition of the core value of "themeability."

Why Themeable SVGs Are Worth Attention

Limitations of Inline Styles

Mermaid's default output inlines colors, strokes, fonts, and other styles on SVG elements. The upside of this approach is that graphics are self-contained and work out of the box, but the cost is that they are hard to integrate with external styling systems. When a documentation site needs to follow users switching between light and dark themes, or when an enterprise needs diagrams to conform to brand guidelines, inline styles become an obstacle.

SVG inline styles vs. external stylesheets: The SVG specification allows styles to be defined in three ways—inline style attributes, CSS embedded within a <style> element, and external CSS introduced via <link> or @import. Mermaid uses the first two by default, causing styles to be coupled with the graphic. The core of themeability is having SVG elements use class or CSS custom properties (CSS Variables), dynamically overridden by external stylesheets or theme systems. Note that when an SVG is referenced as a standalone image via the <img> tag, external CSS does not apply; external styles only take effect when the SVG is inlined into an HTML document or embedded via <object>/<iframe>. Therefore, tools like Pele typically require users to inline the SVG into the page or inject theme variables through a build step.

The Reuse Value of Themeability

A themeable SVG means the same diagram can present different appearances in different contexts without being regenerated. This is especially valuable for documentation systems, design systems, and teams with multiple product lines—the semantic structure of the diagram stays the same, while visual presentation is left to theme control.

Design Tokens: Design tokens are named variables used in design systems to store visual styles (colors, fonts, spacing, etc.), typically existing as JSON or CSS custom properties. Mapping the style attributes in Pele's SVG output to design tokens lets diagrams and product interfaces share the same visual language. For example, binding node fill colors to --color-primary and text colors to --color-text means that when switching themes you only need to update the token values, and all diagrams adapt automatically. This mechanism is also a common implementation of modern front-end theme switching (such as dark mode).

Comparison with Existing Solutions

Mermaid itself provides theme configuration and a CSS class name mechanism, allowing theme variables to be specified at render time. But this kind of configuration is render-time, and the output still leans toward being self-contained. Pele chooses to do theming at the SVG level, which is equivalent to moving control back to the consumer: the graphic structure is generated once, and styles can be overridden as needed. This layered approach aligns with the modern front-end philosophy of "separating structure from style" and is easier to integrate into existing design token systems.

Mermaid theme configuration: Mermaid supports theme customization through the theme and themeVariables configuration options, with built-in themes such as default, dark, forest, and neutral, and also allows overriding variables like colors and fonts. But this configuration takes effect at render time, and the generated SVG still contains a large amount of inline styling. In addition, Mermaid supports adding custom CSS classes to nodes via classDef, but class names are only used at render time, and styles in the output remain predominantly inline. Pele's difference lies in post-processing the generated SVG, removing inline styles and replacing them with CSS classes or variables, transferring style control to the consumer.

Use Cases and Caveats

Pele is suitable for documentation sites, knowledge bases, design system documentation, and diagram scenarios that require brand consistency. Note that the final effect of themeable SVGs depends on the consumer's ability to control SVG styles; if the target environment has restrictions on external SVG styling (for example, some email clients or image embedding scenarios), the themeability may not be fully realized. In addition, the project's discussion on Hacker News is small in scale, and its community ecosystem and long-term maintenance remain to be seen.

Conclusion

Pele targets a real but often overlooked aspect: the visual consistency of diagrams. By outputting Mermaid diagrams as themeable SVGs, letting structure be structure and style be style, this direction has practical significance for documentation and design system teams. Whether it's worth adopting depends on whether your team genuinely needs diagrams to follow theme changes—if so, tools like this can save a lot of the hassle of manual color tweaking.

One-line Summary

Pele converts Mermaid diagrams into themeable SVGs, separating style from structure.

Paragraph Summary

Pele is an open-source tool designed to convert Mermaid diagrams into themeable SVG files, solving the problem that Mermaid's default output with inline styles makes it hard to adapt to light/dark themes and brand guidelines. Traditional Mermaid rendering hard-codes styles such as colors and fonts onto SVG elements, whereas Pele extracts styles from the graphic structure, allowing the same diagram to be reused across different interfaces and documentation styles with only a theme switch to change its appearance. Unlike Mermaid's render-time theme configuration, Pele moves style control to the consumer, better aligning with the modern front-end philosophy of "separating structure from style" and making it easier to integrate with design token systems. The tool suits scenarios requiring visual consistency, such as documentation sites, knowledge bases, and design systems, but community discussion is small in scale, and its long-term maintenance remains to be seen.