Scripts for Extracting Diagram Data in the Diagram-Design Repository

The cathrynlavery/diagram-design repository provides three dedicated Python scripts—drawio_extract.py, mermaid_extract.py, and self_check.py—that parse draw.io XML and Mermaid text into a standardized internal diagram representation.

The cathrynlavery/diagram-design project streamlines diagram manipulation by isolating format-specific parsing logic into dedicated utilities. These scripts for extracting diagram data reside in the skills/diagram-design/scripts directory and serve as the primary interface for converting external diagram formats into the repository's unified internal model.

Core Extraction Scripts

The extraction layer consists of three specialized Python modules. Each script handles a specific aspect of the ingestion pipeline, from parsing proprietary XML formats to validating final data structures.

drawio_extract.py for draw.io XML Processing

Located at skills/diagram-design/scripts/drawio_extract.py, this script handles draw.io (diagrams.net) files using Python's built-in xml.etree.ElementTree library. It extracts geometric shapes, connector paths, and metadata from the XML structure.

# Example: Parsing a draw.io file programmatically

import sys
sys.path.insert(0, 'skills/diagram-design/scripts')
import drawio_extract

# Parse XML into internal representation

with open("architecture.drawio", "r") as f:
    xml_content = f.read()

diagram_model = drawio_extract.parse_xml(xml_content)
nodes = diagram_model["nodes"]
edges = diagram_model["edges"]

mermaid_extract.py for Text-Based Diagrams

The skills/diagram-design/scripts/mermaid_extract.py module processes Mermaid markdown syntax. Unlike the XML approach, this script uses targeted string parsing to interpret flowchart and sequence diagram definitions embedded in markdown blocks.

# Example: Extracting from Mermaid syntax

from skills.diagram_design.scripts import mermaid_extract

mermaid_code = """
graph TD;
    A[Start] --> B{Decision};
    B -->|Yes| C[Action 1];
    B -->|No| D[Action 2];
"""

diagram_data = mermaid_extract.parse_mermaid(mermaid_code)

self_check.py for Data Validation

While not an extractor itself, skills/diagram-design/scripts/self_check.py provides critical schema validation for the output generated by the other two scripts. It ensures that parsed diagram data conforms to expected node and edge schemas before further processing occurs.

# Example: Validating extracted diagram data

from skills.diagram_design.scripts import self_check

validation_result = self_check.validate_diagram(diagram_data)
if not validation_result.is_valid:
    print(f"Validation errors: {validation_result.errors}")

The Four-Step Extraction Workflow

All scripts for extracting diagram data follow a standardized pipeline to ensure consistency across format types:

1. Read the source file, whether draw.io XML or Mermaid markdown text.
2. Parse the content using format-specific methods—xml.etree.ElementTree for draw.io, string tokenization for Mermaid.
3. Transform the parsed structure into a unified internal model containing nodes, edges, and attributes.
4. Validate the resulting model using self_check.py to guarantee schema compliance.

Integration with Repository Commands

These extraction scripts power the high-level import-drawio and import-mermaid commands within the repository. By isolating parsing logic into standalone modules under skills/diagram-design/scripts/, the project maintains separation of concerns and allows direct script invocation from the command line.

# Command-line usage examples

python skills/diagram-design/scripts/drawio_extract.py input.drawio --output diagram.json
python skills/diagram-design/scripts/mermaid_extract.py diagram.md --validate

Summary

• The diagram-design repository includes three primary scripts for extracting diagram data: drawio_extract.py, mermaid_extract.py, and self_check.py.
• drawio_extract.py at skills/diagram-design/scripts/drawio_extract.py handles XML parsing from draw.io files using xml.etree.ElementTree.
• mermaid_extract.py at skills/diagram-design/scripts/mermaid_extract.py processes text-based Mermaid diagram definitions through string parsing.
• self_check.py at skills/diagram-design/scripts/self_check.py validates extracted data against internal schemas to ensure data integrity.
• All scripts support both command-line execution and module import for integration with import-drawio and import-mermaid commands.

Frequently Asked Questions

What diagram formats does the diagram-design repository support?

The repository currently supports draw.io (XML-based) and Mermaid (text-based) formats through dedicated extraction scripts. The modular architecture located in skills/diagram-design/scripts/ allows for straightforward addition of new format parsers.

How does drawio_extract.py parse XML files?

The script utilizes Python's standard library xml.etree.ElementTree module to traverse the draw.io XML structure. It identifies shape elements and connector paths, extracting geometric data and metadata to populate the internal diagram model's nodes and edges according to the repository's unified schema.

Can the extraction scripts be used as standalone tools?

Yes. While designed to support the repository's import-drawio and import-mermaid commands, each script functions independently. You can invoke them directly from the command line or import them as Python modules for use in external applications, as implemented in the cathrynlavery/diagram-design source code.

What validation does self_check.py perform?

The self_check.py script verifies that extracted diagram data conforms to expected schemas, checking for required node attributes, valid edge connections, and data type consistency. This validation step ensures that downstream processing components receive properly structured diagram objects before further manipulation occurs.

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