How to Import and Redraw Mermaid Diagrams with Diagram-Design

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, 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. 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, 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:

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

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

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

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

# 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

# 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 – Defines the CLI interface, argument parsing logic, and high-level workflow orchestration.
• 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 – Guides the skill's discovery of reference files and import parameters.
• references/output-spec.md – Specifies supported output formats, size presets, and visual templates referenced during rendering.
• 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 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 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, 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.

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