Mermaid Grammars Supported for Import and Redraw in Diagram-Design: A Complete Guide

The Diagram-Design skill supports exactly four Mermaid grammars for import and redraw: flowchart/graph, sequenceDiagram, stateDiagram-v2, and erDiagram; all other diagram types trigger a "supported-kinds" error.

Understanding which Mermaid grammars work with the Diagram-Design skill is essential for converting existing diagrams into editable, redrawable formats. This guide covers the specific Mermaid grammars supported for import and redraw, based on the official import-mermaid.md reference documentation in the cathrynlavery/diagram-design repository.

Supported Mermaid Grammars

The Diagram-Design skill recognizes and processes four specific Mermaid grammars. These are explicitly listed in skills/diagram-design/references/import-mermaid.md lines 23-24, which serves as the canonical reference for what's compatible.

Flowchart / Graph (flowchart or graph)

The flowchart and graph grammar is fully supported, including modern Mermaid v11.3+ features:

• Node shorthands using @{ shape: … } syntax
• Multiline Markdown labels
• Classic directional graphs (TB, BT, LR, RL)

This is the most commonly used Mermaid grammar and receives comprehensive support in the extractor.

Sequence Diagram (sequenceDiagram)

Sequence diagrams are supported with normalized handling of:

• Activation suffixes (the + and - markers)
• Central-connection () markers

The extractor normalizes these annotations during the import process before building the intermediate representation.

State Machine Diagram (stateDiagram-v2)

The stateDiagram-v2 grammar for state-machine diagrams is explicitly supported. This covers:

• States and transitions
• Composite states
• Fork and join pseudo-states

Entity-Relationship Diagram (erDiagram)

ER diagrams using the erDiagram grammar are supported, enabling import of:

• Entities with attributes
• Relationship definitions
• Cardinality notation

Unsupported Mermaid Diagram Types

Any Mermaid grammar outside the four listed above will fail with a "supported-kids" error. According to import-mermaid.md lines 106-108, the following popular diagram types are explicitly unsupported:

• pie — Pie charts
• mindmap — Mind maps
• gitGraph — Git commit graphs
• quadrantChart — Quadrant charts
• timeline — Timeline diagrams
• C4Context — C4 architecture diagrams
• sankey — Sankey flow diagrams

Attempting to import these will result in an immediate error before any extraction begins.

How Import and Redraw Works

Extraction to Intermediate Representation

When a supported grammar is detected, the extractor in skills/diagram-design/scripts/mermaid_extract.py converts the source into a structured intermediate representation (IR). This IR mirrors the draw.io internal format but strips all layout-specific information:

• Discarded: Themes, CSS classes, link styles, color schemes, positioning coordinates
• Preserved: Nodes, edges, containers, direction hints, semantic relationships

This extraction approach ensures the redraw step can build fresh, optimal layouts without legacy constraints.

Redraw and Type Mapping

The redraw step maps the extracted IR to the Diagram-Design diagram type system. As documented in import-mermaid.md lines 42-48, you can force specific output types regardless of source grammar:

Source Grammar	Default Output Type	Forced Alternative Types
flowchart/graph	flowchart	architecture, nested
sequenceDiagram	sequence	flowchart
stateDiagram-v2	state machine	flowchart
erDiagram	er	flowchart, architecture

Command-Line Usage Examples

Importing Mermaid files uses the diagram-design:import-mermaid command. Here are practical examples based on the reference documentation and test fixtures:

Import a Simple Flowchart as HTML

diagram-design:import-mermaid scripts/fixtures/sample-flowchart.mmd \
    --format=html --size=doc-inline --detail=balanced --audience=mixed

This processes a .mmd file and outputs a redrawn HTML diagram suitable for inline documentation.

Extract All Diagrams from a Markdown File

diagram-design:import-mermaid docs/README.md --diagram=all --format=svg

When your Markdown contains multiple fenced Mermaid blocks, this renders each as a separate SVG output.

Force a Non-Default Diagram Type

diagram-design:import-mermaid diagrams/transactions.mmd \
    --type=flowchart --format=html --detail=faithful

Even though transactions.mmd contains a sequenceDiagram, this forces the output to use flowchart layout rules.

Key Implementation Files

Understanding the codebase structure helps troubleshoot import issues:

• skills/diagram-design/scripts/mermaid_extract.py — Core extraction logic that parses supported grammars and builds the IR
• skills/diagram-design/references/import-mermaid.md — Canonical reference defining supported grammars, extraction steps, and edge-case handling
• commands/import-mermaid.md — CLI documentation with full argument specifications
• scripts/verify-mermaid-import.py — Test suite validating grammar support and error conditions

Summary

• Four grammars supported: flowchart/graph, sequenceDiagram, stateDiagram-v2, and erDiagram
• All others rejected: pie, mindmap, gitGraph, quadrantChart, timeline, C4Context, sankey, etc. trigger "supported-kinds" errors
• Layout-agnostic extraction: Themes and styling are stripped; semantic content is preserved
• Flexible redraw: Output type can be forced independently of source grammar
• Reference source: import-mermaid.md lines 23-24 and 106-108 define the complete support matrix

Frequently Asked Questions

What happens when I try to import an unsupported Mermaid diagram type?

The importer immediately throws a "supported-kinds" error and terminates without partial extraction. This validation occurs before any parsing begins, as implemented in the grammar detection phase of mermaid_extract.py.

Can I convert a sequence diagram to a flowchart layout?

Yes. Use the --type=flowchart flag to override the default output type. The semantic elements (actors become nodes, messages become edges) are remapped to the target diagram type's conventions during redraw.

Does Diagram-Design preserve Mermaid styling and themes?

No. The extractor deliberately discards all layout-specific information including themes, CSS classes, and link styles. Only semantic content—nodes, edges, containers, and direction hints—survives into the intermediate representation. The redraw step then applies fresh layout algorithms based on your output type and detail level settings.

Are Mermaid v11.3+ features like node shorthands supported?

Yes, but only for the flowchart/graph grammar. The @{ shape: … } shorthand syntax and multiline Markdown labels are explicitly handled in the extractor. These features do not extend to other supported grammars like sequenceDiagram or erDiagram.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}