How to Create a New Diagram Type in diagram-design: A Step-by-Step Guide

Extend the diagram-design repository by creating a reference markdown file, registering the type in SUPPORTED_KINDS, implementing a parser function in mermaid_extract.py, and updating the export registry to follow the existing flowchart pattern.

The diagram-design repository by cathrynlavery provides a structured framework for documenting and parsing Mermaid diagram variants. To maintain consistency with the established reference pattern used for flowcharts, sequence diagrams, and ER diagrams, contributors must follow a six-step integration process that coordinates documentation, CLI recognition, and parser implementation.

Step 1: Create the Reference Markdown Documentation

Every diagram type in diagram-design requires a canonical reference document that defines visual styles, semantic constraints, and usage patterns. Start by copying the existing flowchart template to create your new reference file.

Create skills/diagram-design/references/type-<new>.md using the structure found in type-flowchart.md. The document must include three HTML preview variants (light, dark, and full) displayed in a comparison table:

---
title: "<New> Diagram"
---

## Overview

Description of the diagram type's purpose and visual characteristics.

## Variants

| Light | Dark | Full |
|-------|------|------|
| ![light](../examples/<new>/example-<new>-light.png) | ![dark](../examples/<new>/example-<new>-dark.png) | ![full](../examples/<new>/example-<new>-full.png) |

Reference the style guide at skills/diagram-design/references/style-guide.md to ensure consistent terminology and formatting when describing visual constraints and semantic rules.

Step 2: Register the Diagram Type in the CLI

The extraction engine must recognize your new type before parsing can occur. Open skills/diagram-design/scripts/mermaid_extract.py and locate the SUPPORTED_KINDS constant at approximately line 35.

Add your diagram type to the comma-separated list:

SUPPORTED_KINDS = "flowchart, sequenceDiagram, stateDiagram-v2, erDiagram, myDiagram"

If your diagram uses a custom grammar that varies significantly from built-in types, consider adding it to any unsupported-kinds validation sets to provide helpful error messages when users attempt unsupported syntax combinations.

Step 3: Implement the Parser Logic

The parser implementation requires two modifications to mermaid_extract.py: hooking the kind recognition and writing the parsing routine.

Extend Kind Recognition

In the private function _kind_and_direction (lines 14-31), add a regex branch that identifies your diagram header and returns the appropriate default direction:

if re.match(r"^myDiagram\b", text, re.I):
    return "myDiagram", "LR", position

Create the Parsing Function

Implement a dedicated parser function following the pattern of _parse_flowchart or _parse_sequence. Create _parse_myDiagram that accepts the Diagram object, line tuples, and header position:

def _parse_myDiagram(diagram: Diagram, lines: list[tuple[int, str]], header_position: int) -> None:
    """Parse the custom “myDiagram” grammar."""
    for line_number, raw in lines[header_position + 1 :]:
        text = raw.strip()
        if not text:
            continue
        # Example: simple node definition “A:Label”

        if ":" in text:
            node_id, label = map(str.strip, text.split(":", 1))
            diagram.add_node(node_id, label, "rect")
            continue
        # Example: edge definition “A --> B : description”

        if "-->" in text:
            src, rest = text.split("-->", 1)
            tgt, _, lbl = rest.partition(":")
            diagram.add_edge(src.strip(), tgt.strip(), lbl.strip())
            continue
        # Fallback – raise a helpful error

        _fail(f"unrecognised myDiagram statement at line {line_number}")

Hook into the Main Parser

In the parse_block function (around line 20), add a dispatch branch that routes to your new parser:

elif kind == "myDiagram":
    _parse_myDiagram(diagram, lines, header_position)

Use the internal IR methods diagram.add_node() and diagram.add_edge() to populate the data structure, extending _edge_operators if your syntax requires custom connection operators.

Step 4: Provide Example Source Files and HTML Variants

Place demonstration files in docs/examples/<new>/ following the repository's naming conventions:

• example-<new>.mermaid – Raw Mermaid source code
• example-<new>-light.html – Light theme preview
• example-<new>-dark.html – Dark theme preview
• example-<new>-full.html – Full spectrum variant

Link these files from your reference markdown using standard Markdown image syntax so users can view the visual output alongside the syntax documentation.

Step 5: Update the Export Registry

The export-registry.md file maintains the master list of all exportable diagram types. Add your entry following the existing bullet format:

- **myDiagram** – a custom diagram that … (see `type-myDiagram.md`).

This registry controls which types appear in the export command listings and must stay synchronized with SUPPORTED_KINDS.

Step 6: Validate and Test the Integration

Run the repository's validation workflows to ensure clean integration. Execute the verification scripts from the scripts/ directory:

python3 scripts/verify-myDiagram.py   # if you added a dedicated script

python3 scripts/test-verify-myDiagram.py    # unit test for your parser

If your type reuses an existing parser logic, add test cases to the generic test suites (such as test-verify-*.py) that feed minimal source files and assert expected node and edge counts. Verify that ./scripts/verify-* passes without errors before submitting.

Summary

• Reference documentation lives in skills/diagram-design/references/type-<new>.md and must include light, dark, and full HTML variants.
• CLI registration requires updating SUPPORTED_KINDS in mermaid_extract.py at line 35 and adding recognition logic in _kind_and_direction.
• Parser implementation involves creating a _parse_<type> function and dispatching to it from parse_block using the internal Diagram IR.
• Example files follow the directory structure docs/examples/<new>/ with both source and generated HTML previews.
• Export registry at skills/diagram-design/references/export-registry.md must list the new type for CLI visibility.
• Validation uses scripts in scripts/ to confirm correct node/edge extraction and integration with the CI pipeline.

Frequently Asked Questions

What file defines supported diagram types in diagram-design?

The skills/diagram-design/scripts/mermaid_extract.py file contains the SUPPORTED_KINDS constant at approximately line 35, which declares all valid diagram types for the CLI. You must also update the _kind_and_direction function in the same file to recognize the new type header.

How do I handle custom syntax operators when adding a new diagram type?

Extend the _edge_operators dictionary or create new helper methods within your _parse_<type> function to handle custom connection syntax. The parser should use diagram.add_edge() with the appropriate operator mapping, following the pattern established in _parse_flowchart.

Where should I place example files for a new diagram type?

Place source files and HTML previews in docs/examples/<new>/ using the naming pattern example-<new>.mermaid for source and example-<new>-light.html, example-<new>-dark.html, and example-<new>-full.html for the three visual variants required by the reference documentation.

Do I need to create a separate verification script for each new diagram type?

Separate verification scripts are optional but recommended for complex parsers. You can alternatively add test cases to existing generic test suites like test-verify-*.py that validate node and edge extraction. All tests must pass the ./scripts/verify-* workflows before the new type is considered fully integrated.

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