How the OfficeCLI Diagram Compiler Converts Mermaid Flowcharts into Native Shapes

The OfficeCLI diagram compiler transforms Mermaid flowcharts into native editable Office shapes through a five-stage pipeline: detection, semantic parsing, geometric layout, native emission, and optional image fallback.

The iOfficeAI/OfficeCLI repository provides a command-line interface for automating Microsoft Office documents, with its diagram compiler serving as the core engine that bridges text-based Mermaid diagrams and fully editable Word or PowerPoint graphics. Unlike simple image embedding, this compiler generates native Office DrawingML shapes that users can manipulate after generation.

The Five-Stage Compilation Pipeline

The conversion process follows a sophisticated compiler architecture that moves from text representation to geometric layout to native Office objects.

Stage 1: Mermaid Source Detection

The pipeline begins in src/officecli/Core/Diagram/DiagramCompiler.cs, where the DiagramCompiler.Compile method inspects the first non-comment line of the input Mermaid text. This header detection determines the layout strategy:

• If the header matches flowchart or graph, the compiler delegates to FlowchartLayout.Layout
• If the header matches sequenceDiagram, it routes to SequenceLayout.Layout
• When no explicit header exists, the compiler defaults to flowchart mode (matching Mermaid's native behavior)

Stage 2: Parsing to Semantic IR

Once the diagram type is identified, the selected layout invokes MermaidParser.Parse from src/officecli/Core/Diagram/MermaidParser.cs. This parser tokenizes the Mermaid DSL and constructs a DiagramGraph—a semantic intermediate representation containing nodes (with Id, Label, and Shape properties) and edges (with From, To, and Label properties).

Stage 3: Layout to Geometric IR

The semantic graph undergoes sophisticated layout algorithms depending on diagram type:

Flowchart Layout (src/officecli/Core/Diagram/FlowchartLayout.cs): Implements a full Sugiyama-style layered graph layout, including cycle breaking, longest-path ranking, dummy-node insertion for edge routing, barycentric crossing reduction, Brandes-Köpf coordinate assignment, and final fit-to-canvas scaling.

Sequence Diagram Layout (src/officecli/Core/Diagram/SequenceLayout.cs): Uses a specialized algorithm for positioning lifelines and routing messages between participants.

Both algorithms output a LaidOutGraph—a geometric intermediate representation containing exact X/Y/W/H coordinates for every node and poly-line routes for every edge.

Stage 4: Native Shape Emission

The geometric IR feeds into Office-specific handlers that instantiate native DrawingML objects:

• Word Documents: src/officecli/Handlers/Word/WordHandler.Add.Diagram.cs iterates over LaidOutGraph.Nodes, creates shapes (rectangles, decision diamonds, cylinders) via the Word interop API, and draws routed edges as connectors.
• PowerPoint Presentations: src/officecli/Handlers/Pptx/PowerPointHandler.Add.Diagram.cs performs the same mapping for PPTX slides, ensuring shapes appear as native PowerPoint diagram elements.

Stage 5: PNG Fallback

If the client requests render=image or the native renderer is unavailable, MermaidImageRenderer (located in src/officecli/Core/Diagram/MermaidImageRenderer.cs) renders the Mermaid source to PNG using the bundled Mermaid JS engine, embedding the raster image instead of native shapes.

Command-Line Usage Examples

Generate native editable shapes in PowerPoint using the --render native flag:

officecli add my.pptx /slide[1] textbox \
  --prop text="flowchart TD; A[Start] --> B[Process] --> C[End]" \
  --prop size=32 --prop bold=true \
  --render native

Render the same chart as a static image fallback:

officecli add my.pptx /slide[1] textbox \
  --prop text="flowchart TD; A[Start] --> B[Process] --> C[End]" \
  --render image

Insert a flowchart as native shapes in Word:

officecli add my.docx /body \
  --type diagram \
  --prop text="flowchart LR; X[Input] --> Y[Output]" \
  --render native

Programmatic API Access

Invoke the compiler directly from C# for custom automation workflows:

using OfficeCli.Core.Diagram;

string mermaid = "flowchart TD; A[Start] --> B[Middle] --> C[End]";
LaidOutGraph graph = DiagramCompiler.Compile(mermaid);

// graph now contains positioned nodes & routed edges ready for Office APIs

Summary

• OfficeCLI transforms Mermaid text into native Office shapes through a semantic-to-geometric compilation pipeline.
• DiagramCompiler.Compile in DiagramCompiler.cs orchestrates the process by detecting diagram types and delegating to specialized layouts.
• FlowchartLayout.cs implements Sugiyama-style layered graph layout, while SequenceLayout.cs handles lifeline diagrams.
• Output handlers in WordHandler.Add.Diagram.cs and PowerPointHandler.Add.Diagram.cs convert the geometric IR (LaidOutGraph) into editable DrawingML shapes and connectors.
• MermaidImageRenderer.cs provides PNG fallback when native rendering is disabled or unavailable.

Frequently Asked Questions

What is the difference between native shapes and image rendering in OfficeCLI?

Native shapes produce editable DrawingML objects that users can manipulate in Word or PowerPoint—resizing, recoloring, and modifying text after generation. Image rendering (--render image) generates a static PNG bitmap using the bundled Mermaid JS engine, which cannot be edited as individual shapes but ensures compatibility when the Office interop APIs are unavailable.

Which Mermaid diagram types does the OfficeCLI compiler support?

According to the source code in DiagramCompiler.cs, the compiler explicitly supports flowcharts (including graph and flowchart keywords) and sequence diagrams (triggered by sequenceDiagram headers). When no header is detected, the compiler defaults to flowchart mode to maintain compatibility with standard Mermaid syntax.

How does OfficeCLI determine the positioning of flowchart nodes?

The compiler uses a Sugiyama-style layered graph layout algorithm implemented in FlowchartLayout.cs. This algorithm performs cycle breaking to handle directed graphs, assigns ranks using longest-path layering, inserts dummy nodes for edge routing, reduces crossings via barycentric heuristics, and assigns coordinates using the Brandes-Köpf method before scaling to fit the target canvas dimensions.

Can I use the OfficeCLI diagram compiler in my own .NET applications?

Yes. The compiler exposes a public API through the OfficeCli.Core.Diagram namespace. You can call DiagramCompiler.Compile(string mermaidText) to receive a LaidOutGraph object containing calculated coordinates and dimensions, then feed this data into your own rendering logic or use the built-in Word and PowerPoint handlers provided in the officecli.Handlers namespace.

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