Mermaid Format

The Mermaid format exports Mauro models as Mermaid diagram syntax for visualisation in documentation and development tools.

Overview

The Mermaid format (identifier: mmd) generates diagram definitions in Mermaid syntax. Mermaid is a JavaScript-based diagramming tool that renders text-based diagram definitions into visual diagrams. The CLI supports multiple Mermaid diagram types:

  • Class diagrams (UML-style) - default format
  • Entity-Relationship (ER) diagrams
  • Mindmap diagrams

Format Identifiers

Identifier Diagram Type File Extension
mmd Class Diagram .mmd
mmd-er ER Diagram .mmd
mmd-mindmap Mindmap .mmd

Direction Support

Format Import Export Version
mmd (Class) Yes Yes 1.2.1
mmd-er No Yes 1.0.0
mmd-mindmap No Yes 1.0.0

Class Diagram Parameters

Parameter Type Default Description
mermaid.layoutDirection Choice TB Layout direction: TB (top-bottom) or LR (left-right)
mermaid.showAssociations Boolean true Show association links (reference type elements)
mermaid.includeDataTypes Boolean false Include data types as separate nodes
mermaid.includeEnumerations Boolean true Include enumeration types with their values
mermaid.theme Choice default Visual theme: default, dark, neutral
mermaid.look Choice classic Rendering style: classic or handDrawn
mermaid.hideEmptyMembersBox Boolean false Hide empty attributes/methods sections in class boxes

Diagram Types Explained

Class Diagram (mmd)
UML-style class diagram showing data classes, attributes, and relationships with cardinality. Suitable for technical documentation and software design.
ER Diagram (mmd-er)
Entity-Relationship diagram showing tables, columns, and foreign key relationships. Optimised for database schema documentation.
Mindmap (mmd-mindmap)
Hierarchical mindmap showing model structure and class relationships. Useful for high-level overviews and presentations.

Examples

The following examples illustrate the use of the Mermaid format

Export Class Diagram

MauroImportExport.Cli export mmd model.json diagram.mmd

Export with Custom Layout and Theme

MauroImportExport.Cli export mmd model.json diagram.mmd \
    --param mermaid.layoutDirection=LR \
    --param mermaid.theme=dark \
    --param mermaid.look=handDrawn

Export ER Diagram

MauroImportExport.Cli export mmd-er model.json schema.mmd

Export Mindmap

MauroImportExport.Cli export mmd-mindmap model.json overview.mmd

Import Mermaid Class Diagram

MauroImportExport.Cli import mmd diagram.mmd model.json

Mermaid Syntax Features

Generated Mermaid diagrams include:

  • Class definitions with attributes and their types
  • Relationship arrows showing associations and references
  • Cardinality notation (0..1, 1..*, etc.)
  • Enumeration types with value lists
  • Proper character escaping for special symbols
  • Theme and styling directives

Rendering Mermaid Diagrams

Mermaid diagrams can be rendered using:

  • GitHub Markdown (native Mermaid support in code blocks)
  • Mermaid Live Editor (https://mermaid.live)
  • VS Code with Mermaid Preview extension
  • Mermaid CLI for generating PNG/SVG/PDF
  • GitLab, Azure DevOps (native support)
  • Documentation generators (MkDocs, Docusaurus, etc.)

Best Practices

  • Use TB layout for hierarchical models with inheritance
  • Use LR layout for wide models with many associations
  • Enable hideEmptyMembersBox for cleaner diagrams when classes have no attributes
  • Use ER diagrams for database-focused documentation
  • Use mindmaps for executive summaries and presentations
  • Combine with SVG export for high-quality vector graphics

Import Capabilities

The Mermaid class diagram importer (mmd) can parse:

  • Class definitions with attributes and types
  • Association relationships between classes
  • Cardinality annotations
  • Basic class hierarchies

Note: Import is currently limited to class diagrams. ER and mindmap imports are not supported.