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

> Learn to create a new diagram type in diagram-design. Follow this guide to register, implement parsers, and update the export registry following existing patterns for seamless integration.

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

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md). The document must include three HTML preview variants (light, dark, and full) displayed in a comparison table:

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

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

```python
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:

```python
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:

```python
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`](https://github.com/cathrynlavery/diagram-design/blob/main/export-registry.md) file maintains the master list of all exportable diagram types. Add your entry following the existing bullet format:

```markdown
- **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:

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