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

> Discover the four Mermaid grammars flowchart graph sequenceDiagram stateDiagram-v2 and erDiagram supported for import and redraw in Diagram-Design. Learn more now.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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

```bash
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

```bash
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

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md)** — Canonical reference defining supported grammars, extraction steps, and edge-case handling
- **[`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md)** — CLI documentation with full argument specifications
- **[`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`.