# How to Import and Redraw Mermaid Diagrams with Diagram-Design

> Easily import and redraw Mermaid diagrams using Diagram Design. Securely convert your diagrams into SVG, PNG, and HTML formats for editorial use. Get started today.

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

---

**The Diagram-Design repository provides a secure pipeline to import Mermaid diagrams, extract their structure into a normalized intermediate representation, and redraw them in editorial-style formats including SVG, PNG, and HTML.**

This guide explains how to use the `cathrynlavery/diagram-design` repository to transform Mermaid source files into clean, publication-ready visuals. Whether you are processing standalone `.mmd` files or extracting diagrams from Markdown documents, the workflow treats all input as untrusted data while producing deterministic, style-consistent output.

## The Import Pipeline Architecture

The `import-mermaid` command orchestrates a six-stage pipeline that converts Mermaid syntax into rendered graphics. Each stage is designed to sanitize input, preserve semantic structure, and apply consistent visual styling.

### Command Invocation and Validation

The process begins in [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md), where the CLI parses arguments including `--format`, `--size`, `--detail`, `--audience`, `--variant`, and `--output`. The command validates the supplied file path and determines whether the input is a standalone Mermaid file or a Markdown document containing fenced Mermaid blocks.

### Mermaid Extraction and Normalization

Once invoked, the command calls [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py). This script isolates Mermaid blocks from surrounding content and builds a **normalized intermediate representation (IR)** that captures nodes, edges, fragments, and notes.

The extraction process deliberately discards unsafe content through the `_discard_nonsemantic` helper function. This removes click handlers, style directives, embedded JavaScript, and other potentially hazardous constructs before they reach the rendering stage.

### IR Analysis and Feasibility Testing

After extraction, the script processes the IR through three core functions: `analyze()`, `digest()`, and `to_json()`. These compute statistics including node counts, edge counts, hierarchy depth, and cycle detection. The analysis determines whether the requested detail level is feasible given the chosen size preset, producing a human-readable Markdown digest that summarizes the diagram's topology.

### Rendering and Output Generation

Based on the `--format` flag (HTML, SVG, PNG, or HTML+PNG) and `--variant` (light, dark, or full), the rendering layer draws the diagram using a consistent style guide that overrides Mermaid's default layouts, themes, and fonts. The final files are written to the path specified by `--output` or alongside the source file by default.

The command concludes by printing a fidelity ledger that documents any elements merged, collapsed, or omitted during the redraw process.

## Security Guarantees During Import

The repository treats all Mermaid source text as **untrusted data**. The pipeline never evaluates Mermaid code, never follows click URLs, and never propagates Mermaid-specific directives to the output. All sanitization occurs early in [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py), ensuring that the rendering stage receives only structural, non-executable content.

## Command-Line Examples

Use these patterns to import and redraw diagrams for different production scenarios:

```bash

# Redraw the first diagram in a Mermaid file with default settings

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

```

```bash

# Export as SVG with slide-wide dimensions and simplified detail

diagram-design import-mermaid diagram.mmd \
    --format=svg --size=slide-16x9 --detail=simplified

```

```bash

# Generate both HTML and PNG with dark variant, output to specific folder

diagram-design import-mermaid docs/architecture.md \
    --format=html+png --variant=dark --output=build/diagrams

```

```bash

# Process all Mermaid blocks in a Markdown file, output JSON IR for tooling

diagram-design import-mermaid README.md --json --output=tmp/ir.json

```

## Source File Reference

Understanding these key files helps when extending or debugging the import workflow:

- **[`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md)** – Defines the CLI interface, argument parsing logic, and high-level workflow orchestration.
- **[`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py)** – Contains the core extraction engine, IR construction, safety sanitization via `_discard_nonsemantic`, and analysis utilities (`analyze`, `digest`, `to_json`).
- **[`prompts/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/import-mermaid.md)** – Guides the skill's discovery of reference files and import parameters.
- **[`references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/output-spec.md)** – Specifies supported output formats, size presets, and visual templates referenced during rendering.
- **[`references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/import-mermaid.md)** – Documents default values and semantic definitions for all CLI flags.

## Summary

- The `import-mermaid` command provides a deterministic pipeline for converting Mermaid diagrams to publication-ready formats.
- The extractor in [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) creates a sanitized intermediate representation that strips all executable code and unsafe directives.
- Analysis functions verify feasibility between diagram complexity and requested detail levels before rendering occurs.
- Output supports SVG, PNG, HTML, and combined formats with light, dark, or full variants.
- The entire workflow maintains security by treating source Mermaid as untrusted data and sanitizing it before processing.

## Frequently Asked Questions

### What file formats does the import command support for output?

The command supports four format combinations via the `--format` flag: **SVG** for scalable vector graphics, **PNG** for raster images, **HTML** for interactive web pages, and **HTML+PNG** to generate both simultaneously. You can further customize the visual appearance using the `--variant` flag to select light, dark, or full themes.

### Can I import Mermaid diagrams that are embedded inside Markdown files?

Yes. The [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) script automatically detects and isolates fenced Mermaid blocks (marked by ` ```mermaid `) within Markdown documents. When you point the command at a `.md` file rather than a standalone `.mmd` file, the extractor parses all diagram blocks and processes them through the same normalization and rendering pipeline.

### What is the intermediate representation (IR) and why is it necessary?

The **intermediate representation** is a normalized data structure created by the `analyze()` and `to_json()` functions that captures pure diagram topology—nodes, edges, and annotations—without Mermaid-specific syntax or styling. This abstraction layer allows the system to safely discard unsafe content, validate complexity against size constraints, and render the diagram using editorial style guides rather than Mermaid's default themes.

### How does the repository handle potentially malicious Mermaid code?

All input passes through the `_discard_nonsemantic` helper in [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py), which strips click handlers, style directives, embedded JavaScript, and URL callbacks before they reach the IR stage. The architecture treats source Mermaid as untrusted data, ensuring that the rendering engine never evaluates or executes any code from the input file.