Copilot Instructions for convert2mermaid

Project Overview

convert2mermaid is a Node.js CLI tool that converts diagrams from various formats into Mermaid.js syntax. The tool currently supports Visio (.vsdx) files and is designed to be extensible for other formats like DrawIO and Excalidraw.

Key Architecture

Core Components

index.ts: Main CLI entry point using Commander.js
parser.ts: Central parser dispatcher that routes to format-specific parsers
scribe.ts: Converts internal diagram representation to Mermaid syntax
types.d.ts: Internal data structures for diagrams, shapes, and styles
shapes/flowchartShapes.ts: Maps shape types to Mermaid shape syntax

Current File Format Support

Visio (.vsdx): Uses the
```
vsdx-js
```
npm package (version 1.1.1) ✅
DrawIO (.drawio): XML-based format with custom parser ✅
Excalidraw (.excalidraw): JSON-based format with custom parser ✅

Planned File Format Support

Other formats: Lucidchart, PlantUML, etc.

Data Flow

CLI parses command line arguments
```
parseData()
```
routes to appropriate parser based on file extension
Format-specific parser converts to internal
```
Diagram
```
interface
```
generateMermaidCode()
```
converts
```
Diagram
```
to Mermaid syntax
Output written to .mmd file

Key Interfaces

Diagram

interface Diagram {
    Shapes: Shape[];
    Settings?: string;
}

Shape

interface Shape {
    Id: string;
    ShapeType: string; // Used for Mermaid shape mapping
    Label: string;
    Style: Style;
    IsEdge: boolean;
    FromNode: string; // For edges/connectors
    ToNode: string; // For edges/connectors
}

Style

interface Style {
    FillForeground: string;
    FillBackground: string;
    TextColor: string;
    LineWeight: number;
    LineColor: string;
    LinePattern: number;
    Rounding: number;
    BeginArrow: number;
    BeginArrowSize: number;
    EndArrow: number;
    EndArrowSize: number;
    LineCap: number;
    FillPattern: number;
}

External Dependencies

vsdx-js: Handles Visio file parsing (exports
```
parseVisioFile
```
,
```
VisioFile
```
,
```
VisioShape
```
types)
xml2js: For XML parsing (used by DrawIO parser)
adm-zip: For extracting zip-based formats
commander: CLI argument parsing
figlet: ASCII art title
ora: Loading spinners

Development Guidelines

Adding New Format Support

Create parser in
```
/src/parser/
```
directory (e.g.,
```
drawioParser.ts
```
)
Implement conversion from format-specific types to internal
```
Shape
```
interface
Add case to
```
parseData()
```
switch statement in
```
parser.ts
```
Add file extension to
```
supportedFileTypes
```
array in
```
index.ts
```
Add test files and test cases

Shape Type Mapping

Shape types from input formats must be mapped to
```
ShapeType
```
strings

getMermaidShapeByValue()

flowchartShapes.ts

maps shape types to Mermaid syntax

Add new shape mappings as needed for different formats

Style Handling

Different formats may have different style properties
Convert format-specific styles to the standard
```
Style
```
interface
```
getStyleStatement()
```
in
```
scribe.ts
```
converts styles to Mermaid CSS

Testing

Use Vitest for testing
Add sample files to
```
/tests/
```
directory
Test both parsing and Mermaid output generation

Current Status

✅ Visio (.vsdx) support working with vsdx-js v1.1.1
✅ DrawIO (.drawio) support implemented with custom XML parser
✅ Excalidraw (.excalidraw) support implemented with JSON parser
🔄 Additional formats and enhancements planned

Build & Run

npm run build
node ./dist/index.js -i <inputfile> [-o <outputfile>] [-d flowchart] [-f mmd]

Key Architecture

index.ts: Main CLI entry point using Commander.js

parser.ts: Central parser dispatcher that routes to format-specific parsers

scribe.ts: Converts internal diagram representation to Mermaid syntax

types.d.ts: Internal data structures for diagrams, shapes, and styles

shapes/flowchartShapes.ts: Maps shape types to Mermaid shape syntax

Visio (.vsdx): Uses the

vsdx-js

npm package (version 1.1.1) ✅

DrawIO (.drawio): XML-based format with custom parser ✅

Excalidraw (.excalidraw): JSON-based format with custom parser ✅

Other formats: Lucidchart, PlantUML, etc.

Key Interfaces

interface Diagram {
    Shapes: Shape[];
    Settings?: string;
}

interface Shape {
    Id: string;
    ShapeType: string; // Used for Mermaid shape mapping
    Label: string;
    Style: Style;
    IsEdge: boolean;
    FromNode: string; // For edges/connectors
    ToNode: string; // For edges/connectors
}

interface Style {
    FillForeground: string;
    FillBackground: string;
    TextColor: string;
    LineWeight: number;
    LineColor: string;
    LinePattern: number;
    Rounding: number;
    BeginArrow: number;
    BeginArrowSize: number;
    EndArrow: number;
    EndArrowSize: number;
    LineCap: number;
    FillPattern: number;
}

Development Guidelines

Create parser in

/src/parser/

directory (e.g.,

drawioParser.ts

)

Implement conversion from format-specific types to internal

Shape

interface

Add case to

parseData()

switch statement in

parser.ts

Add file extension to

supportedFileTypes

array in

index.ts

Add test files and test cases

Shape types from input formats must be mapped to

ShapeType

strings

getMermaidShapeByValue()

flowchartShapes.ts

maps shape types to Mermaid syntax

Add new shape mappings as needed for different formats

Different formats may have different style properties

Convert format-specific styles to the standard

Style

interface

getStyleStatement()

scribe.ts

converts styles to Mermaid CSS

Use Vitest for testing

Add sample files to

/tests/

Copilot Instructions for convert2mermaid

Related Skills

Markdown Converter

Nano Banana Pro

1password