# How OfficeCLI Converts Mermaid Syntax to Native Office Shapes

> Discover how OfficeCLI converts Mermaid syntax to native Office shapes using its three stage pipeline. Learn about parsing, layout algorithms, and object emission for editable graphics.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: internals
- Published: 2026-07-17

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```csharp
// 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:

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/MermaidParser.cs), which maps syntax tokens to `FlowShape` enum values and builds a `DiagramGraph`.
- **Layout calculation** happens in [`FlowchartLayout.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.