# OfficeCLI Mermaid Diagram Conversion to Native Shapes: A Complete Technical Guide

> Convert Mermaid diagrams to editable native Office shapes with OfficeCLI. Modify rectangles, diamonds, and connectors directly in Word and PowerPoint. No external image generation needed.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: deep-dive
- Published: 2026-07-12

---

**OfficeCLI converts Mermaid text diagrams into fully editable native Office shapes without requiring external image generation, producing documents where users can modify rectangles, diamonds, and connectors directly in Word or PowerPoint.**

OfficeCLI, developed by iOfficeAI/OfficeCLI, provides a zero-dependency pipeline that transforms Mermaid DSL descriptions into native Office Open XML drawing elements. This OfficeCLI Mermaid diagram conversion to native shapes eliminates the need for bitmap renders while maintaining full editability in the final document.

## How Native Shape Conversion Works

The conversion pipeline operates through four distinct internal stages, requiring no external binaries unless the user explicitly requests image rendering.

### Step 1: Mermaid Text Acquisition

The process begins when the CLI reads the diagram definition from the `add --type diagram` command. The handler accepts the Mermaid source through multiple property keys: `mermaid`, `text`, `dsl`, or `src`.

In [`PowerPointHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.Add.Diagram.cs) (lines 29-46), the system retrieves either an inline string or reads a `.mmd` file from disk. This raw text then feeds directly into the parsing engine without intermediate transformations.

### Step 2: Parsing the DSL with MermaidParser

The `MermaidParser.Parse` method, located in [`src/officecli/Core/Diagram/MermaidParser.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Diagram/MermaidParser.cs) (lines 10-62), transforms the raw Mermaid DSL into a language-agnostic `DiagramGraph` intermediate representation.

This parser handles:
- Flowchart syntax and node-shape wrappers
- Edge operators and directional indicators
- Group expansion for complex diagrams
- Unsupported directive filtering

The resulting `DiagramGraph` contains nodes, edges, and metadata that remain independent of any specific output format.

### Step 3: Layout and Compilation

`DiagramCompiler.Compile`, found in [`src/officecli/Core/Diagram/DiagramCompiler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Diagram/DiagramCompiler.cs) (lines 18-34), selects the appropriate layout engine based on the first meaningful line of the Mermaid source.

Currently supported layout engines include:
- **FlowchartLayout** – Processes standard flowchart TD (top-down) and LR (left-right) syntax
- **SequenceLayout** – Handles sequence diagram interactions

Each layout engine produces a `LaidOutGraph` containing geometric coordinates, connection points, and shape specifications that map directly to Office drawing primitives.

### Step 4: Native Shape Synthesis

The `AddDiagramNative` method walks the `LaidOutGraph` and generates Office Open XML drawing elements (`<w:drawing>` for Word, `<p:spTree>` for PowerPoint). This process, detailed in [`PowerPointHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.Add.Diagram.cs) (lines 64-70), creates native shapes including rectangles, diamonds, circles, and connectors.

Users receive fully editable graphics they can modify, resize, or recolor using standard Office tools, unlike embedded images that require external editing.

## Fallback Image Rendering Pipeline

When the user specifies `render=image` or when the native backend encounters unsupported diagram types, the system falls back to `MermaidImageRenderer`. This component attempts rendering in the following order:

1. **`mmdc`** – The official Mermaid CLI binary, if installed locally
2. **Headless Browser** – Chrome, Chromium, or Edge via `HtmlScreenshot` for high-fidelity rendering

The renderer caches the minified [`mermaid.min.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/mermaid.min.js) library under `~/.officecli/cache`, refreshing it daily via `UpdateChecker`. When rendering completes, the PNG embeds with the original source preserved in the `alt` attribute using the `mermaid:` prefix, enabling round-trip editing later.

## Practical Code Examples

### 1. Creating Native Shapes (Default Behavior)

```bash
officecli add --type diagram --doc my.pptx \
  --properties "mermaid=flowchart TD; A-->B; B-->C"

```

The handler parses the flowchart syntax, invokes `FlowchartLayout`, and inserts editable PowerPoint shapes.

### 2. Forcing PNG Rendering for Unsupported Types

```bash
officecli add --type diagram --doc my.docx \
  --properties "mermaid=pie; A:30; B:70; render=image"

```

`MermaidImageRenderer.RenderToPngFile` executes, attempting `mmdc` first, then falling back to headless browser rendering.

### 3. Retrieving Source from Existing Images

```csharp
// Extract original Mermaid source from a rendered image
var alt = pictureElement.GetAttribute("alt"); 
// Returns: "mermaid:flowchart TD; A-->B"

if (alt.StartsWith(MermaidImageRenderer.SourceTag))
{
    var mermaidSource = alt.Substring(MermaidImageRenderer.SourceTag.Length);
    // Process or re-render the original DSL
}

```

## Key Source Files and Architecture

The implementation spans several critical files:

- **[`src/officecli/Core/Diagram/DiagramCompiler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Diagram/DiagramCompiler.cs)** – Dispatches Mermaid sources to layout engines based on diagram type detection
- **[`src/officecli/Core/Diagram/MermaidParser.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Diagram/MermaidParser.cs)** – Tokenizes and parses Mermaid DSL into intermediate graph structures
- **[`src/officecli/Core/Diagram/MermaidImageRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Diagram/MermaidImageRenderer.cs)** – Manages PNG rendering, binary detection, and mermaid.js caching
- **[`src/officecli/Handlers/Pptx/PowerPointHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Pptx/PowerPointHandler.Add.Diagram.cs)** – PowerPoint-specific command implementation and shape synthesis
- **[`src/officecli/Handlers/Word/WordHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.Add.Diagram.cs)** – Word document handler for native diagram insertion
- **[`src/officecli/Core/HtmlScreenshot.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/HtmlScreenshot.cs)** – Browser automation for headless rendering
- **[`src/officecli/Core/UpdateChecker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/UpdateChecker.cs)** – Daily cache maintenance for the mermaid.js library

## Summary

- **OfficeCLI Mermaid diagram conversion to native shapes** operates entirely within the CLI without external dependencies, producing editable Office graphics
- The four-stage pipeline (acquisition → parsing → layout → synthesis) converts Mermaid DSL into Office Open XML drawing elements
- `MermaidParser` and `DiagramCompiler` handle flowcharts and sequence diagrams, with extensibility for additional layout engines
- Image fallback via `MermaidImageRenderer` supports `mmdc` or headless browsers when native rendering is unavailable
- Original Mermaid source persists in image `alt` attributes, enabling round-trip conversion and editing workflows

## Frequently Asked Questions

### How does OfficeCLI handle Mermaid syntax errors during native conversion?

The `MermaidParser` validates syntax during the parsing stage and throws `MermaidSyntaxException` for genuine errors rather than silently failing or producing broken shapes. This provides clear feedback to the caller about which line or token caused the failure, allowing users to correct the DSL before retrying the conversion.

### Can I convert complex Mermaid diagrams with subgraphs to native PowerPoint shapes?

Yes, the `FlowchartLayout` engine supports group expansion and subgraph processing as implemented in the layout compilation stage. The `LaidOutGraph` structure preserves hierarchical relationships, and `AddDiagramNative` synthesizes grouped shapes that maintain their containment relationships as PowerPoint groups, allowing users to collapse, expand, or edit subgraphs individually.

### What happens if neither mmdc nor a headless browser is available for image rendering?

If both `mmdc` and browser automation fail, `MermaidImageRenderer` returns a specific error indicating the rendering backend is unavailable. The system does not fall back to the native synthesizer automatically when `render=image` is explicitly requested, preserving the user's intent to receive a bitmap. However, removing the `render=image` property triggers the native path, which has zero external dependencies and always succeeds for supported diagram types.

### Where does OfficeCLI store the cached mermaid.js library for image rendering?

The library caches at `~/.officecli/cache` under the user's home directory. `UpdateChecker` manages this cache, checking for updates daily and refreshing the minified [`mermaid.min.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/mermaid.min.js) file when newer versions become available. This prevents repeated network fetches during batch operations while ensuring the CLI uses current Mermaid syntax support.