Mermaid Builder

0.0.3 · active · verified Wed Apr 15

Mermaid Builder is a Python library designed to programmatically generate MermaidJS markup, facilitating the creation of various diagrams like flowcharts and sequence diagrams from Python code. It allows developers to script the creation of MermaidJS definitions, which can then be rendered in compatible environments such as Markdown files, GitHub, or online Mermaid playgrounds. The library is in early development, with its current version being 0.0.3, indicating rapid iteration and ongoing feature additions.

Warnings

breaking The library is in early development (version 0.0.3) and explicitly marked as 'Work in progress'. This means its API is subject to frequent changes, and backward compatibility is not guaranteed between minor versions.
Fix: Refer to the latest GitHub README and PyPI project description before upgrading. Pin exact versions in your `requirements.txt`.
gotcha This library generates MermaidJS *markup*, but does not render the diagrams itself. To visualize the diagrams, you will need a separate Mermaid.js rendering engine (e.g., a web browser with `mermaid.js` loaded, a Markdown viewer like GitHub, or the `mmdc` CLI tool which requires Node.js).
Fix: Ensure your environment has a suitable MermaidJS renderer available to consume the generated markup. For command-line rendering, consider installing `mmdc` (`npm install -g @mermaid-js/mermaid-cli`).
gotcha The PyPI project description lists several 'Next tasks' such as 'styling for flowchart (adding classes and styles)' and 'class diagrams'. This indicates that certain advanced MermaidJS features might not yet be fully implemented or supported by `mermaid-builder`.
Fix: Check the project's GitHub repository or documentation for the current status of feature implementation. Contribute or open an issue if a desired feature is missing.
gotcha When MermaidJS diagrams are rendered in applications with dynamic theming (e.g., dark/light modes in some markdown editors), custom colors defined in the generated markup might be unexpectedly inverted or altered due to CSS filters applied by the rendering environment.
Fix: If precise color control is critical across themes, you may need to implement custom CSS overrides in your rendering environment or experiment with neutral color palettes that adapt better to inversion filters. Consult the Mermaid.js documentation on theming.

Install

pip install mermaid-builder Install latest version

Imports

Chart
```
from mermaid_builder.flowchart import Chart
```
Commonly used for creating flowchart diagrams.
Node
```
from mermaid_builder.flowchart import Node
```
Used to define nodes within a flowchart.

Quickstart

This quickstart demonstrates how to create a simple flowchart using `mermaid-builder`. It initializes a `Chart`, adds `Node` objects, defines links between them, and then renders the MermaidJS markdown string. The generated string can be pasted into a MermaidJS compatible viewer or Markdown file to visualize the diagram.

from mermaid_builder.flowchart import Chart, Node

# Create a new flowchart
chart = Chart("MyCompanyHierarchy", direction="TD") # Top Down direction

# Add nodes
node_a = Node("Company A")
node_b = Node("Company B")
node_c = Node("Company C")
node_d = Node("Company D")

chart.add_node(node_a)
chart.add_node(node_b)
chart.add_node(node_c)
chart.add_node(node_d)

# Define relationships
chart.link(node_a, node_b)
chart.link(node_a, node_c)
chart.link(node_b, node_d)

# Generate the MermaidJS markup
mermaid_markup = chart.render()
print(mermaid_markup)

# To view this diagram, paste the output into a MermaidJS editor (e.g., mermaid.live)
# or use in a Markdown file that supports Mermaid rendering (e.g., GitHub).

view raw JSON →