Can OfficeCLI Render Mermaid Diagrams? Complete Support Guide

Yes, OfficeCLI can render Mermaid diagrams as PNG images and embed them into Word and PowerPoint documents using a built-in headless Chromium renderer.

OfficeCLI from iOfficeAI is an open-source command-line tool designed for automated Microsoft Office document generation. For developers looking to render Mermaid diagrams programmatically, the tool provides a native rendering pipeline that converts Mermaid markup into embedded PNG images, eliminating the need for manual diagram creation or external conversion tools.

How OfficeCLI Renders Mermaid Diagrams

The Core Rendering Architecture

The rendering engine resides in Core/Diagram/MermaidImageRenderer.cs. This class downloads the Mermaid JavaScript library from https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js and executes it within a headless Chromium instance to generate PNG files.

Before attempting to render, the code invokes MermaidImageRenderer.IsAvailable() to verify the Mermaid JS runtime is present. If the runtime is unavailable, the system falls back to storing the raw Mermaid text as an alt-tag for later processing rather than failing silently.

Rendering Pipeline and Error Handling

The primary entry point MermaidImageRenderer.RenderToPngFile(mermaidText) handles the end-to-end conversion process:

1. Parses the Mermaid source text
2. Loads the Mermaid JS library (cached locally after first download)
3. Executes rendering in headless Chromium
4. Outputs a PNG file to the temporary directory

If the Mermaid syntax contains errors, the renderer throws a MermaidSyntaxException with a clear message format: "mermaid syntax error: …". This exception propagates to the user interface, providing immediate feedback on formatting mistakes without crashing the document generation process.

Supported Mermaid Diagram Types in OfficeCLI

The current implementation supports a specific subset of Mermaid syntax through the parser located in Core/Diagram/MermaidParser.cs.

Currently Supported Types

Flowcharts represent the primary supported diagram type. The parsing follows this pipeline:

• MermaidParser.cs extracts the flowchart structure into an intermediate representation
• Core/Diagram/DiagramCompiler.cs dispatches to the appropriate layout engine
• FlowchartLayout calculates node positioning and edge routing
• MermaidImageRenderer produces the final PNG file

Planned and Unsupported Types

While the architecture supports extension, other diagram types have limited or no implementation:

• Sequence diagrams: Layout logic exists in Core/Diagram/SequenceLayout.cs but is not yet connected to the rendering pipeline
• Gantt, class, state, and other diagrams: No dedicated layout implementations currently exist in the codebase

Adding Mermaid Diagrams to Office Documents

OfficeCLI exposes diagram functionality through AddDiagramAsync methods in both Word and PowerPoint handlers.

Word Documents

To add a diagram to a Word document, use the integration found in Handlers/Word/WordHandler.Add.Diagram.cs:

var mermaid = @"
flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
";

await officeCli.AddDiagramAsync(
    documentPath: "Report.docx",
    diagramText: mermaid,
    renderMode: "native"   // “native” tries the Mermaid renderer first
);

When renderMode is set to "native" and MermaidImageRenderer.IsAvailable() returns true, the diagram renders as a PNG and embeds directly into the document at the current cursor position.

To force image-only rendering regardless of native availability:

await officeCli.AddDiagramAsync(
    documentPath: "Report.docx",
    diagramText: mermaid,
    renderMode: "image",   // forces PNG rendering
    forceImage: true
);

PowerPoint Presentations

The Handlers/Pptx/PowerPointHandler.Add.Diagram.cs handler provides identical functionality for slide decks:

await officeCli.AddDiagramAsync(
    presentationPath: "Deck.pptx",
    diagramText: mermaid,
    renderMode: "native",
    slideIndex: 3
);

The same MermaidImageRenderer is reused across both document types, ensuring consistent output quality and caching behavior.

Performance Optimization and Caching

OfficeCLI implements a caching mechanism via CacheDir to store the downloaded mermaid-11.min.js file. This eliminates repeated downloads of the Mermaid library across command executions, significantly improving performance for batch diagram generation.

The cache persists the JavaScript runtime locally after the first successful download from the CDN, ensuring subsequent renders use the local copy rather than fetching the 11.x MB file repeatedly.

Summary

• OfficeCLI can render Mermaid diagrams natively using a headless Chromium engine located in Core/Diagram/MermaidImageRenderer.cs
• Currently supports flowchart syntax only, with sequence diagram support planned (SequenceLayout.cs exists but is not yet integrated)
• Integrates with both Word (WordHandler.Add.Diagram.cs) and PowerPoint (PowerPointHandler.Add.Diagram.cs) document generation pipelines
• Throws MermaidSyntaxException for invalid markup, providing clear error messages to users
• Caches the Mermaid JS library (mermaid-11.min.js) in CacheDir to optimize repeated renders and reduce network dependencies
• Supports both automatic native rendering and forced image modes via the renderMode parameter

Frequently Asked Questions

What Mermaid diagram types does OfficeCLI support?

Currently, OfficeCLI only supports the flowchart subset of Mermaid syntax through the parser in Core/Diagram/MermaidParser.cs. While Core/Diagram/SequenceLayout.cs contains preliminary layout logic for sequence diagrams, it is not yet connected to the rendering pipeline. Other types including Gantt, class, and state diagrams are not supported at this time.

How does OfficeCLI handle Mermaid syntax errors?

When the renderer encounters invalid Mermaid markup, it throws a MermaidSyntaxException with a descriptive message starting with "mermaid syntax error: …". This exception propagates through the command execution pipeline, allowing users to identify and correct formatting issues in their diagram definitions before the document generation fails.

Can I use OfficeCLI without Chromium installed?

No. The MermaidImageRenderer requires a headless Chromium instance to execute the JavaScript-based Mermaid rendering. The IsAvailable() method checks for the presence of the required Mermaid JS runtime, and if rendering dependencies are missing, the system either falls back to storing raw text (when not forcing image mode) or fails with an appropriate error message.

Does OfficeCLI cache the Mermaid JavaScript library?

Yes. OfficeCLI stores the downloaded mermaid-11.min.js file in the CacheDir directory after the first download from https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js. This caching mechanism prevents redundant network requests and significantly improves performance when generating multiple diagrams in succession or processing batch operations.

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