Diagram Types for Structure in Diagram Design: 4 Supported Mermaid Kinds Explained

The Diagram Design library supports four structural diagram types—flowchart, sequenceDiagram, stateDiagram-v2, and erDiagram—based on Mermaid's grammar, as defined in skills/diagram-design/scripts/mermaid_extract.py.

When working with the cathrynlavery/diagram-design repository, you can create structural visualizations using specific Mermaid diagram grammars recognized by the core parser. The library processes files with extensions .mmd, .mermaid, or fenced code blocks in Markdown to identify and render these diagram types correctly.

The Four Supported Diagram Types for Structure

According to the source code in mermaid_extract.py, the constant SUPPORTED_KINDS declares exactly four diagram kinds that the parser recognizes for structural visualizations:

Diagram Kind	Typical Use Case	Default Direction
flowchart (also called graph)	General-purpose process or hierarchy diagrams	LR (left-to-right)
sequenceDiagram	Interaction flows between participants	LR
stateDiagram-v2	Finite-state or state-machine diagrams	TD (top-down)
erDiagram	Entity-relationship / data-model diagrams	TD

Each kind is automatically detected by the detect_kind helper routine, which matches the leading keyword of a Mermaid block to determine the appropriate parser behavior and default layout direction.

How Diagram Detection Works in the Source Code

In skills/diagram-design/scripts/mermaid_extract.py, the parser analyzes the leading keyword of each Mermaid block to classify the diagram. When processing input, the system returns a structured object containing the kind, direction, and start position, enabling downstream tools to handle validation, rendering, and export operations.

The detection mechanism differentiates between flowcharts (which may be declared as either flowchart or graph), sequence diagrams, state machines, and entity-relationship models based on the first token of the diagram definition.

Working with Structural Diagrams

You can interact with these diagram types using either the command-line interface or Python programmatically.

Command-Line Usage

Import and analyze Mermaid files directly from the terminal:

# Import a Mermaid file and list the detected diagram types

diagram-design import-mermaid path/to/example.mmd

Python Programmatic Usage

Access the parser directly to analyze diagram structures:

from skills.diagram_design.scripts.mermaid_extract import Diagram, parse_block

# Load a Mermaid snippet

source = """
stateDiagram-v2
    [*] --> Idle
    Idle --> Running
    Running --> [*]
"""

# Create a Diagram object and analyze it

diagram = Diagram(index=0, kind="stateDiagram-v2", source_line=0, direction="TD")
info = parse_block(diagram)
print(info)   # → {'kind': 'stateDiagram‑v2', 'direction': 'TD', ...}

Example Flowchart Syntax

For quick reference, here is valid syntax for the flowchart kind:

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Continue]
    B -->|No| D[Stop]

Summary

• Four structural types are supported: flowchart, sequenceDiagram, stateDiagram-v2, and erDiagram, as defined in SUPPORTED_KINDS.
• Detection logic resides in skills/diagram-design/scripts/mermaid_extract.py using the detect_kind function.
• Default directions vary by type: flowcharts and sequence diagrams default to LR (left-to-right), while state and ER diagrams default to TD (top-down).
• File support includes .mmd, .mermaid, and Markdown fenced code blocks.
• Integration available via CLI (diagram-design import-mermaid) or Python API (Diagram class and parse_block function).

Frequently Asked Questions

What file formats does Diagram Design accept for structural diagrams?

The library processes three input formats: standalone files with .mmd or .mermaid extensions, and fenced code blocks within Markdown files. The parser in mermaid_extract.py automatically detects the diagram kind from the leading keyword regardless of the container format.

How does the parser determine the direction of a structural diagram?

The detect_kind function assigns default directions based on diagram type: flowchart and sequenceDiagram default to LR (left-to-right), while stateDiagram-v2 and erDiagram default to TD (top-down). These defaults are applied when processing the diagram block unless overridden by explicit syntax in the Mermaid source.

Can I use the 'graph' keyword instead of 'flowchart'?

Yes. The source code recognizes both flowchart and graph as valid identifiers for the same diagram kind. The SUPPORTED_KINDS constant and detection logic in mermaid_extract.py treat these keywords equivalently when parsing structural diagrams.

Where can I find the CLI documentation for importing diagrams?

The command-line documentation is located in commands/import-mermaid.md, while detailed usage guides reside in skills/diagram-design/references/import-mermaid.md. Both files provide comprehensive instructions for using the diagram-design import-mermaid command with the four supported structural diagram types.

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