How OfficeCLI Converts Mermaid Syntax to Native Office Shapes

OfficeCLI transforms Mermaid diagrams into editable Office graphics through a three-stage pipeline: parsing syntax into a semantic intermediate representation (DiagramGraph), running a Sugiyama layout algorithm to calculate geometric coordinates (LaidOutGraph), and emitting native Word or PowerPoint drawing objects.

OfficeCLI is an open-source command-line tool that bridges the gap between text-based diagramming and native Office documents. When you need to convert Mermaid syntax to native shapes, the tool compiles your ASCII definitions into fully editable Word or PowerPoint graphics that users can modify after insertion. This conversion relies on a sophisticated compiler architecture implemented across several core files in the repository.

The Three-Stage Compilation Pipeline

The conversion process implemented in iOfficeAI/OfficeCLI follows a classic compiler architecture with three distinct stages. Each stage transforms the diagram representation into a progressively more concrete format, ultimately yielding native Office drawing elements.

Stage 1: Parsing Mermaid into Semantic IR

In src/officecli/Core/Diagram/MermaidParser.cs, the MermaidParser.Parse method walks the raw Mermaid text and extracts node identifiers using regular-expression patterns. It determines each node's visual kind—such as rectangle, diamond, or ellipse—and builds a semantic intermediate representation called DiagramGraph.

Each node's shape is stored as a FlowShape enum value defined in DiagramModel.cs. This enum provides the mapping between Mermaid syntax tokens (like [Start] for rectangles or {Decision} for diamonds) and their corresponding Office shape presets. The parser handles various node definitions and edge connections, creating a graph structure that represents the logical flow without geometric positioning.

Stage 2: Layout and Coordinate Calculation

The DiagramCompiler.Compile method in src/officecli/Core/Diagram/DiagramCompiler.cs serves as the pipeline coordinator. It examines the first meaningful line of the Mermaid definition to determine the diagram type (flowchart or sequence diagram). For flowcharts, it invokes FlowchartLayout.Layout from src/officecli/Core/Diagram/FlowchartLayout.cs.

This layout engine implements a faithful port of the Python reference Sugiyama algorithm:

1. Cycle breaking removes circular dependencies
2. Ranking assigns nodes to layers based on longest-path calculations
3. Dummy node insertion creates intermediate points for edge routing
4. Barycenter crossing reduction minimizes edge intersections
5. Coordinate calculation computes geometric positions in centimeters for every node and edge

The output is a geometric intermediate representation—LaidOutGraph—containing PlacedNode objects with calculated X, Y, W, and H values. Each PlacedNode retains its FlowShape enum from the parsing stage, ensuring the visual type information persists through the layout transformation.

Stage 3: Emitting Native Office Shapes

The final stage converts the geometric representation into native Office drawing objects. The emitter—implemented in Word and PowerPoint specific handlers—iterates over LaidOutGraph.Nodes and creates appropriate native elements:

• For Word: <w:drawing> elements with precise positioning
• For PowerPoint: native PPTX shapes with geometric transforms

For each PlacedNode, the emitter uses the stored FlowShape value to select the appropriate preset (rectangle, diamond, ellipse, etc.) and applies the calculated X, Y, W, and H coordinates for placement. Edges become orthogonal connector polylines. Because these are native Office objects rather than images, users can edit them directly within Word or PowerPoint after generation.

Complete Implementation Example

The following C# code demonstrates the complete pipeline as implemented in the source:

// 1️⃣ Parse Mermaid text (normally done inside AddDiagramNative)
string mermaid = @"
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Result]
    B -->|No| D[Alternative]
";
DiagramGraph semantic = MermaidParser.Parse(mermaid);

// 2️⃣ Layout to geometric coordinates
LaidOutGraph geometry = FlowchartLayout.Layout(semantic);

// 3️⃣ Emit native shapes (simplified)
foreach (var n in geometry.Nodes)
{
    // n.Shape tells the emitter which preset to use.
    // e.g., FlowShape.Process → rectangle, FlowShape.Decision → diamond
    DrawNativeShape(id: n.Id, shape: n.Shape,
                    x: n.X, y: n.Y, w: n.W, h: n.H);
}

You can invoke this pipeline from the command line:

# Add a flowchart as native, editable shapes

officecli add --type diagram \
    --render=native \
    -- mermaid "flowchart TD; A[Start] --> B{Decision}; B -->|Yes| C[Result]; B -->|No| D[Alt]"

Summary

• Mermaid parsing occurs in MermaidParser.cs, which maps syntax tokens to FlowShape enum values and builds a DiagramGraph.
• Layout calculation happens in FlowchartLayout.cs using the Sugiyama algorithm to produce a LaidOutGraph with centimeter-accurate coordinates.
• Native emission creates editable Word or PowerPoint drawing objects using the geometric data and shape presets from the previous stages.
• The entire pipeline preserves editability by generating native Office XML rather than raster images.

Frequently Asked Questions

What algorithm does OfficeCLI use for diagram layout?

OfficeCLI uses a port of the Sugiyama algorithm implemented in FlowchartLayout.Layout. This algorithm performs cycle breaking, node ranking, dummy node insertion, and barycenter crossing reduction to minimize edge intersections while calculating geometric coordinates for flowchart nodes.

Can I edit the shapes after conversion?

Yes. Because OfficeCLI emits native Office drawing objects rather than images, the resulting shapes in Word or PowerPoint remain fully editable. You can modify text, resize shapes, change colors, and adjust connectors using the standard Office editing tools.

Where does the shape mapping occur?

The mapping from Mermaid syntax to Office shape types occurs in MermaidParser.Parse within src/officecli/Core/Diagram/MermaidParser.cs. This method assigns FlowShape enum values (such as FlowShape.Process for rectangles or FlowShape.Decision for diamonds) based on the node's syntax in the Mermaid definition.

Which diagram types are currently supported?

According to the source code in DiagramCompiler.cs, the system examines the first meaningful line to determine diagram type. While the architecture supports multiple types, the current implementation specifically handles flowcharts through the FlowchartLayout class, with sequence diagram support indicated in the compiler's type detection logic.

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