panel-mermaid 0.2.0

A project providing a Mermaid JS widget for use with HoloViz Panel.

panel-mermaid

Overview

panel-mermaid is an interactive widget-based tool designed to integrate Mermaid JS diagramming functionality with HoloViz Panel.

This package provides a seamless interface for creating and customizing Mermaid diagrams directly in Python, with the ability to edit configurations and styles interactively. Works in Jupyter notebooks and in your Panel data app.

Key Features

• Interactive Mermaid Diagrams: Easily create flowcharts, sequence diagrams, class diagrams, and more using the familiar Mermaid syntax.
• Configurable Themes and Looks: Choose from a variety of themes (default, dark, forest, etc.) and looks (classic, handDrawn).
• Real-time Configuration Updates: Use the MermaidConfiguration widget to dynamically update your diagram’s configuration.
• Customizable Events: Handle diagram interactions with event subscriptions (e.g., click, mouseover).
• Font-Awesome Icon Support: Leverage Font-Awesome icons in your diagrams by including the Font-Awesome CSS in your application.

Installation

You can install the package using pip:

pip install panel-mermaid

Usage

1. Basic Mermaid Diagram

Here’s how to create a simple Mermaid diagram using the MermaidDiagram widget:

import panel as pn

from panel_mermaid import MermaidDiagram

pn.extension()

MermaidDiagram(
    object=(
        """
        graph LR
            A[Hello] --> B[Panel] --> E[World]
            A-->C(Mermaid) --> E ;
        """
    )
).servable()

Try on PY.CAFE

2. Customizing the Configuration

Use the configuration parameter to modify the Mermaid diagram configuration:

import panel as pn

from panel_mermaid import MermaidDiagram

pn.extension()

MermaidDiagram(
    object=(
        """
        graph LR
            A[Hello] --> B[Panel] --> E[World]
            A-->C(Mermaid) --> E ;
        """
    ),
    configuration={"look": "handDrawn", "theme": "forest"},
).servable()

Try on PY.CAFE

3. Event Handling

You can also add event listeners to the diagram, allowing interactivity such as responding to clicks on diagram nodes:

import panel as pn

from panel_mermaid import MermaidDiagram, MermaidConfiguration

pn.extension()

diagram = MermaidDiagram(
    object=(
        """
        graph LR
            A[Hello] --> B[Panel] --> E[World]
            A-->C(Mermaid) --> E ;
        """
    ),
    event_configuration=[("click", ".node")]
)

pn.FlexBox(diagram, pn.pane.JSON(diagram.param.event, theme="light")).servable()

Try it on PY.CAFE

4. Mermaid SVG Value

If you would like the Mermaid SVG value to be updated would will need to set update_value=True:

from io import StringIO
import panel as pn
from panel_mermaid import MermaidDiagram

pn.extension()

diagram = MermaidDiagram(
    object=(
        """
        graph LR
            A[Hello] --> B[Panel] --> E[World]
            A-->C(Mermaid) --> E ;
        """
    ),
    update_value=True,
)

pn.FlexBox(
    pn.Column(
        diagram,
        diagram.param.update_value,
    ),
    pn.Column(
        pn.widgets.TextAreaInput(value=diagram.param.value, disabled=True, height=200),
        pn.widgets.FileDownload(
            file=pn.bind(StringIO, diagram.param.value), filename="diagram.svg"
        ),
    ),
).servable()

Try on PY.CAFE

5. Mermaid Configuration

The MermaidConfiguration widget allows you to adjust diagram styling and themes interactively, making it simple to adapt to various visual preferences. You can customize:

• Look: Choose between classic or handDrawn.
• Theme: Choose from several themes like default, dark, forest, etc.

Example:

import panel as pn

from panel_mermaid import MermaidDiagram, MermaidConfiguration

pn.extension()

configuration = MermaidConfiguration(look="handDrawn", theme="forest")
diagram = MermaidDiagram(
    object=(
        """
        graph LR
            A[Hello] --> B[Panel] --> E[World]
            A-->C(Mermaid) --> E ;
        """
    ),
    configuration=configuration,
)

pn.FlexBox(configuration, diagram).servable()

Try on PY.CAFE

Font-Awesome Icons

To use Font-Awesome icons in your Mermaid diagrams, include the Font-Awesome CSS. Once included, you can add icons to your diagrams by prefixing with fa::

import panel as pn

from panel_mermaid import MermaidDiagram

pn.extension(sizing_mode="stretch_width", css_files=["https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.6.0/css/all.min.css"])

MermaidDiagram(
    object=(
        """
        graph LR
            A[Hello] --> B[fa:fa-chart-simple Panel] --> E[World]
            A-->C(fa:fa-diagram-project Mermaid) --> E ;
        """
    )
).servable()

Try it on PY.CAFE

Diagram Editor

Check out the live Diagram Editor Code or App.

Contributions

We welcome contributions to this project! Please feel free to submit issues or pull requests to the GitHub repository. Check out the DEVELOPER_GUIDE for more info.

License

This project is licensed under the MIT License.

Alternative Projects

• mermaid-py
• PyMermaid
• pymermaider
• python-mermaid
• streamlit-mermaid

---

Start building rich, interactive diagrams directly in your Python applications with panel-mermaid!