How OfficeCLI Converts Mermaid Diagrams to Native Editable Shapes

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, 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. 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 orchestrates the insertion logic, delegating geometry creation to 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 manages slide insertion, while 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 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:

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:

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:

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 converts Mermaid DSL into a DiagramGraph intermediate representation.
• Layout: DiagramCompiler.cs calculates positions and produces a LaidOutGraph with explicit coordinates.
• Generation: Handler files (WordHandler.Add.Diagram.cs, PowerPointHandler.Add.Diagram.cs) translate the layout into native Office shapes using helper utilities.
• Fallback: 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 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, 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.

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