# How OfficeCLI Converts Mermaid Diagrams to Native Editable Shapes

> Learn how OfficeCLI converts Mermaid diagrams to editable shapes in Word or PowerPoint. Discover the parsing, layout calculation, and native object mapping process.

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

---

**OfficeCLI transforms Mermaid markup into fully editable Word or PowerPoint shapes by parsing the DSL into a graph structure, calculating layouts via `DiagramCompiler`, and mapping the results to native Office drawing objects.**

The iOfficeAI/OfficeCLI open-source project bridges the gap between text-based diagramming and the Microsoft Office ecosystem. When you convert Mermaid to native editable shapes, the tool executes a multi-stage pipeline that translates diagram markup into Open XML drawing elements, preserving full editability within the final document.

## The Native Rendering Pipeline

The conversion from Mermaid text to editable Office graphics follows a strict three-phase architecture: parsing, layout, and shape generation.

### Step 1: Parsing Mermaid DSL with MermaidParser

The process begins in [`Core/Diagram/MermaidParser.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Core/Diagram/MermaidParser.cs), where the `MermaidParser.Parse` method tokenizes the incoming Mermaid source. This parser validates syntax and constructs an intermediate representation called `DiagramGraph`, which abstracts nodes, edges, and diagram metadata into language-agnostic objects. By decoupling the markup syntax from the output format, the parser ensures that layout engines receive a uniform data structure regardless of whether the input is a flowchart, sequence diagram, or pie chart.

### Step 2: Layout Calculation via DiagramCompiler

Once the graph is built, control passes to [`Core/Diagram/DiagramCompiler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Core/Diagram/DiagramCompiler.cs). The `DiagramCompiler` selects a specialized layout engine—such as `FlowchartLayout` or `SequenceLayout`—based on the diagram type detected during parsing. It computes explicit coordinates for every element, producing a `LaidOutGraph` that contains positioned nodes with width, height, and connector routing information. This step is critical for ensuring that the final shapes do not overlap and that connectors route cleanly between elements.

### Step 3: Generating Native Office Shapes

With coordinates established, platform-specific handlers instantiate native Office objects:

- **Word Documents**: [`Handlers/Word/WordHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Handlers/Word/WordHandler.Add.Diagram.cs) orchestrates the insertion logic, delegating geometry creation to [`Handlers/Word/WordHandler.ImageHelpers.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Handlers/Word/WordHandler.ImageHelpers.cs). These helpers generate Word `Shape` elements for nodes and `Connector` elements for edges, inserting them into the document body with the computed layout preserved.

- **PowerPoint Presentations**: [`Handlers/Pptx/PowerPointHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Handlers/Pptx/PowerPointHandler.Add.Diagram.cs) manages slide insertion, while [`Handlers/Pptx/PowerPointHandler.NodeBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Handlers/Pptx/PowerPointHandler.NodeBuilder.cs) constructs individual PowerPoint shape objects. Each `LaidOutGraph` node becomes a native PowerPoint shape that can be resized, recolored, or re-typed directly within the slide editor.

## Alternative: Image-Based Rendering

When the `render` property is set to `image`, or when the native pipeline prerequisites are missing, the system falls back to raster generation. [`Core/Diagram/MermaidImageRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Core/Diagram/MermaidImageRenderer.cs) handles this via the `ComposeSource` method, which prepares the Mermaid DSL for processing. The `RenderToPngFile` method then executes the Mermaid JavaScript bundle—cached locally or retrieved from a CDN—to produce a PNG bitmap. The `MermaidImageRenderer.IsAvailable()` method checks for the local Node.js runtime and Mermaid installation before attempting compilation, ensuring graceful degradation.

## Command-Line Usage Examples

Generate editable shapes in a Word document:

```bash
officecli add report.docx /body \
  --type diagram \
  --prop render=native \
  --prop text="flowchart TD\n    Start-->Process\n    Process-->End"

```

Insert a native sequence diagram into PowerPoint:

```bash
officecli add slides.pptx /slide[2] \
  --type diagram \
  --prop render=native \
  --prop text="sequenceDiagram\n    Alice->>Bob: Hello\n    Bob->>Alice: Hi"

```

Force PNG rendering when native conversion is unavailable:

```bash
officecli add summary.docx /body \
  --type diagram \
  --prop render=image \
  --prop text="pie title Cloud Costs\n    \"Compute\":60\n    \"Storage\":40"

```

## Summary

- **Parsing**: [`MermaidParser.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/MermaidParser.cs) converts Mermaid DSL into a `DiagramGraph` intermediate representation.
- **Layout**: [`DiagramCompiler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/DiagramCompiler.cs) calculates positions and produces a `LaidOutGraph` with explicit coordinates.
- **Generation**: Handler files ([`WordHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Add.Diagram.cs), [`PowerPointHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.Add.Diagram.cs)) translate the layout into native Office shapes using helper utilities.
- **Fallback**: [`MermaidImageRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/MermaidImageRenderer.cs) provides PNG output when native rendering is disabled or unsupported.
- **Editability**: Native mode produces standard Office drawing objects that remain fully editable after insertion.

## Frequently Asked Questions

### What file handles the initial parsing of Mermaid syntax?

The [`Core/Diagram/MermaidParser.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Core/Diagram/MermaidParser.cs) file contains the `MermaidParser` class, which exposes the `Parse` method. This method transforms raw Mermaid text into a structured `DiagramGraph` that downstream components can consume uniformly.

### How does OfficeCLI decide between native shapes and PNG images?

The decision is driven by the `render` property passed via the command line. When set to `native`, the pipeline executes the full graph-to-shapes conversion. If set to `image`, or if `MermaidImageRenderer.IsAvailable()` returns false due to missing dependencies, the system calls `MermaidImageRenderer.RenderToPngFile` to generate a static bitmap instead.

### Can I edit the generated shapes after insertion?

Yes. When using `render=native`, the resulting objects are standard Office Open XML shapes—not embedded images. In Word, these appear as individual flowchart shapes and connectors; in PowerPoint, they become native slide elements. You can resize, recolor, retype text, and reposition them using the standard Office UI.

### What layout engines are supported for native rendering?

According to the source in [`Core/Diagram/DiagramCompiler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Core/Diagram/DiagramCompiler.cs), the compiler dispatches to specialized engines based on diagram type, including `FlowchartLayout` for flowcharts and `SequenceLayout` for sequence diagrams. Each engine implements specific algorithms to prevent node overlap and route connectors, ensuring the final document matches the semantic structure of the original Mermaid markup.