Mermaid Config

Overview

Mermaid is a JavaScript-based diagramming and charting tool that renders Markdown-inspired text definitions to create diagrams dynamically. See here for the official Mermaid docs or here for an online playground.

Unlike D2 and Graphviz, Mermaid diagrams don't require any external executable to be installed - they're rendered directly in Markdown viewers like GitHub, GitLab, and many IDEs including IntelliJ IDEA. This makes Mermaid diagrams highly portable and easy to share.

Mermaid-specific configuration is performed from the mermaid { } block within the base atlas extension function:

plugins {
  id("dev.jonpoulton.atlas.mermaid") version "x.y.z"
}

atlas {
  // other Atlas config - see common config docs

  mermaid {
    animateLinks = false
    look = Look.HandDrawn
    theme = Theme.Forest

    elk {
      mergeEdges = true
      nodePlacementStrategy = NodePlacementStrategy.LinearSegments
      cycleBreakingStrategy = CycleBreakingStrategy.Interactive
      considerModelOrder = ConsiderModelOrder.PreferEdges
      forceNodeModelOrder = true
    }

    layout {
      // custom layout properties
    }

    themeVariables {
      background = "white"
      fontFamily = "arial"
      lineColor = "#55FF55"
      primaryBorderColor = "#FF5555"
      primaryColor = "#ABC123"
    }
  }
}

or a barebones config:

plugins {
  id("dev.jonpoulton.atlas.mermaid") version "x.y.z"
}

The above barebones config will output a diagram like below:

graph TD
  _android_app[":android:app"]
  _android_lib[":android:lib"]
  _java[":java"]
  _kotlin_jvm[":kotlin:jvm"]
  _kotlin_kmp[":kotlin:kmp"]
  _other[":other"]
  _android_app --> _android_lib
  _android_app --> _kotlin_kmp
  _android_lib --> _kotlin_jvm
  _android_lib --> _other
  _java --> _other
  _kotlin_kmp --> _android_lib
  _kotlin_kmp --> _java
  _kotlin_kmp --> _kotlin_jvm

Generated Files

The Mermaid plugin will generate a chart.mmd file in each subproject's atlas/ folder, containing the Mermaid flowchart diagram for that project's dependencies. In the root project, it will also generate a legend.md file containing a legend of any defined project types and link types.

These .mmd files can be embedded directly in Markdown files or rendered by compatible viewers (such as this page!). Many platforms (GitHub, GitLab, etc.) will automatically render Mermaid diagrams when viewing .md files containing mermaid code blocks.

Properties

animateLinks

atlas {
  mermaid {
    animateLinks = true
  }
}

When enabled, links between all project nodes will have animation applied to them. Disabled by default.

See the Mermaid docs for more details.

graph TD
  _android_app[":android:app"]
  _android_lib[":android:lib"]
  _java[":java"]
  _kotlin_jvm[":kotlin:jvm"]
  _kotlin_kmp[":kotlin:kmp"]
  _other[":other"]
  _android_app link0@--> _android_lib
  _android_app link1@--> _kotlin_kmp
  _android_lib link2@--> _kotlin_jvm
  _android_lib link3@--> _other
  _java link4@--> _other
  _kotlin_kmp link5@--> _android_lib
  _kotlin_kmp link6@--> _java
  _kotlin_kmp link7@--> _kotlin_jvm
  link0@{ animate: true }
  link1@{ animate: true }
  link2@{ animate: true }
  link3@{ animate: true }
  link4@{ animate: true }
  link5@{ animate: true }
  link6@{ animate: true }
  link7@{ animate: true }

look

atlas {
  mermaid {
    look = Look.HandDrawn
  }
}

Controls the visual style of the diagram. Available options:

Look.Classic      // Standard clean diagram style (default)
Look.HandDrawn    // Sketch-like hand-drawn appearance

The HandDrawn look gives diagrams a more informal, sketchy appearance similar to Excalidraw.

See the Mermaid docs for more details.

Look.HandDrawn:

---
config:
  look: handDrawn
---
graph TD
  _android_app[":android:app"]
  _android_lib[":android:lib"]
  _java[":java"]
  _kotlin_jvm[":kotlin:jvm"]
  _kotlin_kmp[":kotlin:kmp"]
  _other[":other"]
  _android_app --> _android_lib
  _android_app --> _kotlin_kmp
  _android_lib --> _kotlin_jvm
  _android_lib --> _other
  _java --> _other
  _kotlin_kmp --> _android_lib
  _kotlin_kmp --> _java
  _kotlin_kmp --> _kotlin_jvm

Look.Classic:

graph TD
  _android_app[":android:app"]
  _android_lib[":android:lib"]
  _java[":java"]
  _kotlin_jvm[":kotlin:jvm"]
  _kotlin_kmp[":kotlin:kmp"]
  _other[":other"]
  _android_app --> _android_lib
  _android_app --> _kotlin_kmp
  _android_lib --> _kotlin_jvm
  _android_lib --> _other
  _java --> _other
  _kotlin_kmp --> _android_lib
  _kotlin_kmp --> _java
  _kotlin_kmp --> _kotlin_jvm

theme

atlas {
  mermaid {
    theme = Theme.Forest
  }
}

Applies a built-in Mermaid color scheme to your charts. Available options:

Theme.Default   // Mermaid's default theme
Theme.Neutral   // Neutral colors
Theme.Dark      // Dark mode theme
Theme.Forest    // Forest green theme
Theme.Base      // Minimal base theme

See the Mermaid docs for all available themes.

Neutral	Dark
Forest	Base

Functions

elk

atlas {
  mermaid {
    // use the default configs:
    elk()

    // customise the layout config:
    elk {
      mergeEdges = true
      nodePlacementStrategy = NodePlacementStrategy.LinearSegments
      cycleBreakingStrategy = CycleBreakingStrategy.Interactive
      considerModelOrder = ConsiderModelOrder.PreferEdges
      forceNodeModelOrder = true
    }
  }
}

Configures the ELK (Eclipse Layout Kernel) layout engine for Mermaid diagrams. See the Mermaid ELK configuration docs for detailed information. Basic output for the default configuration:

mergeEdges

Allows edges to share paths where convenient. Can create cleaner diagrams but may be harder to follow in complex graphs. Defaults to false.

nodePlacementStrategy

Controls how nodes are positioned within layers. Defaults to NodePlacementStrategy.BrandesKoepf.

Simple	NetworkSimplex
LinearSegments	BrandesKoepf

cycleBreakingStrategy

Determines how to find and break cycles in the graph. Defaults to CycleBreakingStrategy.GreedyModelOrder. Options:

• Greedy
• DepthFirst
• Interactive
• ModelOrder

These can't easily be demonstrated because they don't affect simple diagrams, but the option's here if you need it.

considerModelOrder

Controls whether to preserve the order of nodes/edges from the model file. Defaults to ConsiderModelOrder.NodesAndEdges. Options:

• None
• NodesAndEdges
• PreferEdges
• PreferNodes

These can't easily be demonstrated because they don't affect simple diagrams, but the option's here if you need it.

forceNodeModelOrder

Preserves the model's node order without changes during layout. Requires considerModelOrder to be set appropriately. Defaults to false.

layout

atlas {
  mermaid {
    layout {
      name = "dagre"
      put("customProperty", "value")
    }
  }
}

Allows you to set a custom layout engine name and any additional properties. The default layout engine is "dagre" if not specified.

The layout function is primarily useful if: 1. You want to explicitly set the layout to "dagre" (though this is the default) 2. Future Mermaid versions add new layout engines 3. You need to pass custom properties using the put() method

This function implements PropertiesSpec, so you can use put("key", value) to add custom key/value pairs.

See the Mermaid docs on layouts.

themeVariables

atlas {
  mermaid {
    themeVariables {
      background = "#FFF"
      darkMode = true
      fontFamily = "arial"
      fontSize = "16px"
      lineColor = "#55FF55"
      primaryBorderColor = "#FF5555"
      primaryColor = "#ABC123"
      primaryTextColor = "#000"
      secondaryColor = "#DEF456"
      tertiaryColor = "#789ABC"

      // Use put() for any additional theme variables
      put("defaultLinkColor", "#5555FF")
    }
  }
}

Configures global theme variables that control the appearance of the diagram. These variables allow fine-grained control over colors and styling beyond what the preset themes provide.

Available typed properties:

Colors can be specified as:

• CSS color names (e.g., "red", "forestgreen")
• Hex values (e.g., "#FF5555", "#ABC123")
• RGB/RGBA values (e.g., "rgb(255, 85, 85)")

Project Type Styling

When configuring project types for Mermaid, you can use Mermaid-specific styling properties:

atlas {
  projectTypes {
    androidApp()
    kotlinMultiplatform {
      fontColor = "white"
      fontSize = "20px"
      stroke = "#FF5555"
      strokeDashArray = "4 3 2 1"
      strokeWidth = "3px"
    }
    other()
  }
}

Available properties for MermaidProjectTypeSpec:

Link Type Styling

When configuring link types for Mermaid, you can use Mermaid-specific styling properties:

atlas {
  linkTypes {
    api(LinkStyle.Basic) {
      fontColor = "blue"
      stroke = "red"
      strokeWidth = "5px"
    }

    implementation(LinkStyle.Dashed) {
      stroke = "aqua"
      strokeDashArray = "5 5"
    }

    "jvmMainImplementation"(LinkStyle.Bold, color = "orange")
  }
}

Available link styles:

LinkStyle.Basic      // Solid line with arrow (default)
LinkStyle.Bold       // Thick solid line with arrow
LinkStyle.Dashed     // Dashed line with arrow
LinkStyle.Invisible  // Hidden link (still affects layout)

Basic	Bold
Dashed	Invisible

Available properties for MermaidLinkTypeSpec:

See the Mermaid docs on link styling.