Convert diagrams from Visio, DrawIO, Excalidraw, and PlantUML into Mermaid syntax. The project can be used as a command-line converter or imported as an npm package by other Node.js/TypeScript modules.
It is useful for keeping diagrams in version control, generating Mermaid blocks for Markdown documentation, and migrating existing diagram files into a text-based format.
- Multiple input formats:
.vsdx,.drawio,.excalidraw,.puml, and.plantuml - Multiple Mermaid targets:
flowchart,classDiagram,sequenceDiagram,stateDiagram-v2,block-beta,erDiagram,gantt,mindmap, andtimeline - CLI and npm package usage: run conversions from the terminal or call the parser/generator from application code
- TypeScript declarations: package exports include generated
.d.tsfiles - Diagram type detection: source files are analyzed with confidence scores before Mermaid generation
- DrawIO flowchart fallback: ambiguous DrawIO diagrams can fall back to Mermaid
flowchart - Shape and style preservation: labels, common shapes, colors, line styles, arrows, and fills are preserved where possible
Install as a dependency:
npm install convert2mermaidInstall globally if you want the convert2mermaid command available in your shell:
npm install -g convert2mermaidFor local development:
git clone https://github.com/jgreywolf/convert2mermaid.git
cd convert2mermaid
npm install
npm run buildAfter installing globally or using the built package:
convert2mermaid -i input.drawio -o output.mmdFrom this repository:
# Run the built CLI. Requires npm run build first.
npm start -- -i tests/drawio.drawio -f mmd
# Run TypeScript source during development.
npm run dev -- -i tests/drawio.drawio -f md
# Call the built CLI directly.
node dist/cli.js -i tests/drawio.drawio -o tests/drawio.mmdIf --outputFile is not provided, the output path is derived from the input filename and --outputFormat.
convert2mermaid [options]
Required:
-i, --inputFile <path> Input diagram file
Optional:
-o, --outputFile <path> Output file path
-f, --outputFormat <mmd|md> Output format, defaults to mmd
-d, --diagramType <type> Reserved for explicit diagram type usage
-dffc, --drawioFallbackFlowchartConfidence DrawIO fallback threshold, defaults to 50
-dffc / --drawioFallbackFlowchartConfidence controls how DrawIO type detection handles ambiguous diagrams.
DrawIO files often contain generic rectangles, ellipses, text, and arrows without explicit semantic metadata. When a specialized type such as class, component, sequence, state, ER, or network is detected below the configured confidence percentage, the converter uses Mermaid flowchart instead. This usually produces more renderable output because Mermaid flowcharts tolerate generic node/edge structures better than specialized diagram syntaxes.
Examples:
# Default fallback threshold: 50
convert2mermaid -i diagram.drawio -o diagram.mmd
# Require stronger specialized detection before leaving flowchart mode
convert2mermaid -i diagram.drawio -o diagram.mmd -dffc 70
# Allow weaker specialized detection
convert2mermaid -i diagram.drawio -o diagram.mmd -dffc 30The package exports parser and generator helpers from dist/index.js.
import { convertToMermaid, parseDiagram, generateMermaidCode } from 'convert2mermaid';
const result = await convertToMermaid('diagram.drawio', {
outputFormat: 'mmd',
drawioFallbackFlowchartConfidence: 50,
});
console.log(result.mermaid);
console.log(result.analysis?.detectedType);
console.log(result.analysis?.confidence);
const parsed = await parseDiagram('diagram.drawio');
if (parsed) {
const mermaid = generateMermaidCode(parsed);
console.log(mermaid);
}Parses a source file, generates Mermaid syntax, and returns the diagram model, Mermaid output, and optional detection analysis.
const result = await convertToMermaid('diagram.puml', {
outputFormat: 'md',
drawioFallbackFlowchartConfidence: 60,
});Options:
{
outputFormat?: 'mmd' | 'md';
drawioFallbackFlowchartConfidence?: number;
silent?: boolean;
}Returns:
{
diagram: Diagram;
mermaid: string;
analysis?: DiagramAnalysis;
}Parses a source file and returns the internal diagram model without generating Mermaid.
const diagram = await parseDiagram('diagram.drawio', {
drawioFallbackFlowchartConfidence: 50,
});Generates Mermaid syntax from an already parsed diagram object.
Lower-level parser entry point used internally by the CLI and API. Most callers should prefer parseDiagram or convertToMermaid.
Supported targets:
- Flowcharts: process flows, decisions, documents, databases, data stores, manual inputs, and generic connected shapes
- Class diagrams: UML-style classes, attributes, methods, stereotypes, and relationships
- Sequence diagrams: actors, participants, lifelines, messages, activation-like regions, and frame labels such as
par,alt,loop, andopt - State diagrams: states, transitions, initial states, final states, and basic state labels
- Component diagrams: components, modules, packages, containers, and dependencies
- Entity-relationship diagrams: entities, attributes, relationships, and cardinality-like labels
- Network diagrams: network devices, server-like nodes, cloud nodes, and infrastructure connections
DrawIO detection is heuristic. It reads structured mxCell data including labels, styles, edge relationships, geometry, parent/child grouping, and shape hints. Some shapes are semantically useful, for example umlActor, umlLifeline, startState, endState, module, component, entity, and Cisco/network shapes. Generic rectangles and arrows are intentionally handled conservatively.
Supported shape categories include:
- Basic: rectangles, rounded rectangles, circles, ellipses, diamonds, triangles, hexagons
- Flowchart: process, decision, document, database, delay, display, manual input, stored data
- UML: actors, lifelines, frames, notes, components, modules
- Specialized: cylinders, parallelograms, trapezoids, clouds, paper tape, network device shapes
Examples:
# Generic DrawIO diagram
convert2mermaid -i diagram.drawio -o diagram.mmd
# DrawIO to Markdown with a Mermaid code block
convert2mermaid -i diagram.drawio -o diagram.md -f md
# Raise fallback threshold for ambiguous DrawIO files
convert2mermaid -i diagram.drawio -o diagram.mmd -dffc 80Supported targets:
- Class diagrams: classes, interfaces, abstract classes, enumerations, attributes, methods, visibility modifiers, stereotypes, and UML relationships
- Component diagrams: components, packages, databases, nodes, and dependency-style relationships
- State diagrams: states, transitions, initial/final states, and common transition labels
- Sequence diagrams: participants, actors, messages, activations, and common message arrows
- Use case diagrams: actors, use cases, include/extend-style relationships
- Activity diagrams: activities, decisions, start/stop nodes, and simple flows
- Gantt charts: basic tasks, milestones, and durations
Common UML relationship mappings include:
--|>inheritance..|>implementationo--aggregation*--composition-->association/dependency-style links
Examples:
convert2mermaid -i class-model.puml -o class-model.mmd
convert2mermaid -i sequence.puml -o sequence.md -f md
convert2mermaid -i architecture.plantuml -o architecture.mmdVisio support focuses on basic shape and connector conversion:
- Flowchart-like pages
- Basic diagrams with shapes and connectors
- Text labels on shapes and connectors
- Basic style preservation where the parser exposes useful metadata
Example:
convert2mermaid -i flowchart.vsdx -o flowchart.mmdExcalidraw support focuses on sketch-style diagrams:
- Rectangles, diamonds, ellipses, and other basic elements
- Connectors and arrows
- Text label extraction
- Flowchart-style Mermaid output
Example:
convert2mermaid -i sketch.excalidraw -o sketch.mmdThe detection layer analyzes diagram content before generation and attaches analysis metadata to the parsed diagram.
Detection considers:
- File type and parser result
- Shape styles and semantic shape names
- Edge count, direction, and connectivity
- Labels that look like UML members, stereotypes, participants, states, or ER attributes
- Parent/child grouping such as swimlanes, containers, packages, and modules
- Known PlantUML directives such as
@startumland@startgantt
Example CLI output:
Detected diagram type: flowchart (35% confidence)
Detection evidence:
- flowchart: Found generic nodes and directed edges (35%)
Diagram metadata: 4 shapes, 3 edges
For DrawIO, unknown or low-confidence specialized detections can fall back to flowchart through the drawioFallbackFlowchartConfidence option.
Writes raw Mermaid syntax:
flowchart TD
A["Start"] --> B["End"]
Writes a Markdown file containing a Mermaid fenced code block:
```mermaid
flowchart TD
A["Start"] --> B["End"]
```- Flowcharts:
flowchart TDorflowchart LR - Class diagrams:
classDiagram - Sequence diagrams:
sequenceDiagram - State diagrams:
stateDiagram-v2 - Component diagrams:
block-beta - ER diagrams:
erDiagram - Gantt charts:
gantt - Mind maps:
mindmap - Timelines:
timeline
PowerShell:
Get-ChildItem diagrams -Filter *.drawio | ForEach-Object {
convert2mermaid -i $_.FullName -o "output/$($_.BaseName).mmd"
}Bash:
for file in diagrams/*.puml; do
convert2mermaid -i "$file" -o "output/$(basename "$file" .puml).mmd"
done{
"scripts": {
"diagrams": "convert2mermaid -i docs/architecture.drawio -o docs/architecture.mmd"
}
}import { writeFile } from 'node:fs/promises';
import { convertToMermaid } from 'convert2mermaid';
const { mermaid, analysis } = await convertToMermaid('docs/architecture.drawio', {
outputFormat: 'mmd',
drawioFallbackFlowchartConfidence: 70,
});
console.log(`Detected ${analysis?.detectedType} at ${analysis?.confidence}%`);
await writeFile('docs/architecture.mmd', mermaid);npm install
npm run build
npm test
npm run test:watch
npm run dev -- -i tests/drawio.drawio -f mmdPackage validation:
npm pack --dry-run --jsonnpm pack and npm publish run npm run build first through the prepack script.
src/
├── index.ts Public package exports
├── api.ts Library API: convertToMermaid, parseDiagram, generateMermaidCode
├── cli.ts Command-line entry used by the package bin
├── scribe.ts Dispatches parsed diagrams to Mermaid generators
├── types.d.ts Shared diagram model types
├── parser/ Format-specific parsers and parser dispatcher
│ ├── BaseParser.ts Shared parser base behavior
│ ├── parser.ts File extension dispatch and parseData entry point
│ ├── drawioParser.ts DrawIO XML parser
│ ├── plantumlParser.ts PlantUML text parser
│ └── excalidrawParser.ts Excalidraw JSON parser
├── detection/ Diagram type detection
│ ├── DetectorFactory.ts Reads files and routes to the right detector
│ ├── DiagramDetector.ts Shared detection logic and common scoring
│ ├── DrawIODetector.ts DrawIO-specific heuristics and flowchart fallback
│ ├── PlantUMLDetector.ts PlantUML-specific heuristics
│ ├── types.ts Detection result and option types
│ └── index.ts Detection exports
├── generators/ Mermaid syntax generators
│ ├── flowchartGenerator.ts Generates Mermaid flowchart syntax for generic node/edge diagrams
│ ├── classGenerator.ts Generates classDiagram syntax for UML-style classes and relationships
│ ├── sequenceGenerator.ts Generates sequenceDiagram syntax for participants and messages
│ ├── stateGenerator.ts Generates stateDiagram-v2 syntax for states and transitions
│ ├── componentGenerator.ts Generates block-beta syntax for component/module diagrams
│ ├── erGenerator.ts Generates erDiagram syntax for entities and relationships
│ ├── ganttGenerator.ts Generates Mermaid gantt syntax for simple schedules
│ ├── mindmapGenerator.ts Generates mindmap syntax for hierarchical diagrams
│ ├── networkGenerator.ts Generates flowchart-style output for network diagrams
│ └── timelineGenerator.ts Generates timeline syntax for ordered events
├── shapes/ Shape mappings and Mermaid shape helpers
│ ├── flowchartShapes.ts
│ └── shapeMappers.ts
└── utils/ Shared utility functions
├── classUtils.ts
├── errorUtils.ts
├── labelUtils.ts
├── relationshipUtils.ts
└── styleUtils.ts
Test files live next to the code they validate and use the *.spec.ts suffix.
Input:
@startuml
class User {
+id: String
+name: String
+login()
+logout()
}
interface Authenticatable {
+authenticate()
+getToken()
}
User ..|> Authenticatable : implements
@endumlOutput:
classDiagram
class User {
+id: String
+name: String
+login()
+logout()
}
class Authenticatable
<<interface>> Authenticatable {
+authenticate()
+getToken()
}
User ..|> Authenticatable : implements
Input:
@startuml
[*] --> Idle
Idle --> Processing : start
Processing --> Success : complete
Processing --> Error : fail
Success --> [*]
Error --> Idle : retry
@endumlOutput:
stateDiagram-v2
[*] --> Idle
Idle --> Processing : start
Processing --> Success : complete
Processing --> Error : fail
Success --> [*]
Error --> Idle : retry
- DrawIO does not always store explicit diagram type metadata, so detection is heuristic.
- Generic DrawIO shapes are ambiguous and may intentionally fall back to
flowchart. - Mermaid layout is not coordinate-based like DrawIO, Visio, or Excalidraw, so exact visual positioning is not preserved.
- Multi-page diagrams are not fully supported.
- Very complex PlantUML syntax may need manual adjustment after conversion.
- Gantt support is basic; advanced PlantUML Gantt features such as sections and date formatting may need additional work.
Contributions are welcome.
- Fork the repository.
- Create a feature branch.
- Add focused tests for behavior changes.
- Run
npm run buildandnpm test. - Open a pull request.
MIT. See LICENSE.
- Built with TypeScript
- Mermaid syntax targets Mermaid.js
- Uses vsdx-js for Visio parsing
- XML parsing with xml2js
- CLI built with commander
- Tests run with Vitest