Yog.Render.Mermaid (YogEx v0.70.0)

Copy Markdown View Source

Mermaid.js format export for embedding diagrams in web pages and documents.

This module exports graphs to Mermaid syntax, a JavaScript-based diagramming tool that renders diagrams from text definitions. Mermaid is supported natively in GitHub, GitLab, Notion, and many other platforms.

Quick Start

# Export to Mermaid syntax
mermaid = Yog.Render.Mermaid.to_mermaid(my_graph, Yog.Render.Mermaid.default_options())

# Use in Markdown:
# ```mermaid
# graph TD
#     A[Node 1] --> B[Node 2]
# ```

Supported Diagram Types

This module generates flowchart-style diagrams:

  • Graph TD: Top-down (vertical) layout
  • Graph LR: Left-to-right (horizontal) layout
  • Graph BT: Bottom-to-top layout
  • Graph RL: Right-to-left layout

Customization

Control styling via options/0:

  • Node shapes (rounded, rectangular, circular, rhombus, hexagon, etc.)
  • Labels and edge annotations
  • Highlight specific nodes or edges
  • Direction and orientation
  • CSS-based styling with custom lengths

Embedding Options

PlatformMethod
GitHub/GitLabNative Markdown support
NotionMermaid code block
VS CodeMermaid extension
Static siteMermaid.js library
JupyterMermaid magic commands

Live Editor

Test and refine diagrams at Mermaid Live Editor.

References

Migration Note: Enhanced in v0.53.0 with full Gleam parity: all node shapes, CSS length types, comprehensive styling options.

Summary

Types

css_length()

CSS length unit for styling.

direction()

Direction for graph layout

node_shape()

Node shape options for Mermaid diagrams.

options()

Options for customizing Mermaid diagram rendering

Functions

default_options()

Creates default Mermaid options with simple labeling.

path_to_options(path, base_options)

Converts a shortest path result to highlighted Mermaid options.

to_mermaid(graph, options)

Converts a graph to Mermaid diagram syntax.

Types

css_length()

@type css_length() ::
  {:px, integer()}
  | {:em, float()}
  | {:rem, float()}
  | {:percent, float()}
  | {:custom, String.t()}

CSS length unit for styling.

Mermaid supports various CSS length units:

  • :px - Pixels (most common)
  • :em - Ems (relative to font size)
  • :rem - Rems (relative to root font size)
  • :percent - Percentage
  • {:custom, string} - Custom CSS value (for advanced users)

direction()

@type direction() :: :td | :lr | :bt | :rl

Direction for graph layout

node_shape()

@type node_shape() ::
  :rounded_rect
  | :stadium
  | :subroutine
  | :cylinder
  | :circle
  | :asymmetric
  | :rhombus
  | :hexagon
  | :parallelogram
  | :parallelogram_alt
  | :trapezoid
  | :trapezoid_alt

Node shape options for Mermaid diagrams.

Each shape has a specific Mermaid syntax:

  • :rounded_rect - [label] - Rectangle with rounded corners
  • :stadium - ([label]) - Stadium shape (pill)
  • :subroutine - [[label]] - Subroutine shape (rectangle with side lines)
  • :cylinder - [(label)] - Cylindrical shape (database)
  • :circle - ((label)) - Circle
  • :asymmetric - >label] - Asymmetric shape (flag)
  • :rhombus - {label} - Rhombus (decision)
  • :hexagon - {{label}} - Hexagon
  • :parallelogram - [/label/] - Parallelogram
  • :parallelogram_alt - [\label\] - Parallelogram alt
  • :trapezoid - [/label\] - Trapezoid
  • :trapezoid_alt - [\label/] - Trapezoid alt

options()

@type options() :: %{
  node_label: (Yog.node_id(), any() -> String.t()),
  edge_label: (any() -> String.t()),
  highlighted_nodes: [Yog.node_id()] | nil,
  highlighted_edges: [{Yog.node_id(), Yog.node_id()}] | nil,
  direction: direction(),
  node_shape: node_shape(),
  highlight_fill: String.t(),
  highlight_stroke: String.t(),
  highlight_stroke_width: css_length(),
  link_thickness: css_length(),
  highlight_link_stroke: String.t(),
  highlight_link_stroke_width: css_length()
}

Options for customizing Mermaid diagram rendering

Functions

default_options()

@spec default_options() :: options()

Creates default Mermaid options with simple labeling.

Uses node ID as label and edge weight as-is. Default configuration:

  • Direction: Top-to-bottom (TD)
  • Node shape: Rounded rectangle
  • Highlight: Yellow fill with orange stroke

Examples

iex> opts = Yog.Render.Mermaid.default_options()
iex> opts.direction
:td
iex> opts.node_shape
:rounded_rect
iex> opts.highlight_fill
"#ffeb3b"

path_to_options(path, base_options)

@spec path_to_options(map(), options()) :: options()

Converts a shortest path result to highlighted Mermaid options.

Creates a copy of the base options with the path's nodes and edges set to be highlighted.

Example

case Yog.Pathfinding.Dijkstra.shortest_path(...) do
  {:some, path} ->
    options = Yog.Render.Mermaid.path_to_options(path, Yog.Render.Mermaid.default_options())
    mermaid = Yog.Render.Mermaid.to_mermaid(graph, options)
  :none ->
    ""
end

to_mermaid(graph, options)

@spec to_mermaid(Yog.graph(), options()) :: String.t()

Converts a graph to Mermaid diagram syntax.

The graph's node data and edge data must be convertible to strings. Use the options to customize labels and highlight specific paths.

Time Complexity: O(V + E)

Example

graph =
  Yog.directed()
  |> Yog.add_node(1, "Start")
  |> Yog.add_node(2, "Process")
  |> Yog.add_node(3, "End")
  |> Yog.add_edge!(from: 1, to: 2, with: "5")
  |> Yog.add_edge!(from: 2, to: 3, with: "3")

# Basic rendering
diagram = Yog.Render.Mermaid.to_mermaid(graph, default_options())

# Highlight a path
options = %{
  default_options() |
  highlighted_nodes: [1, 2, 3],
  highlighted_edges: [{1, 2}, {2, 3}]
}
highlighted = Yog.Render.Mermaid.to_mermaid(graph, options)

The output can be embedded in markdown:

```mermaid
graph TD
  1["Start"]
  2["Process"]
  3["End"]
  1 -->|5| 2
  2 -->|3| 3
```