# Can OfficeCLI Render Mermaid Diagrams? Complete Support Guide

> Learn if OfficeCLI can render Mermaid diagrams. Discover how OfficeCLI uses a headless Chromium renderer to embed PNG diagrams into Word and PowerPoint documents.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-07-14

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Core/Diagram/MermaidParser.cs).

### Currently Supported Types

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

- [`MermaidParser.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/MermaidParser.cs) extracts the flowchart structure into an intermediate representation
- [`Core/Diagram/DiagramCompiler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Handlers/Word/WordHandler.Add.Diagram.cs):

```csharp
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:

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

```

### PowerPoint Presentations

The [`Handlers/Pptx/PowerPointHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Handlers/Pptx/PowerPointHandler.Add.Diagram.cs) handler provides identical functionality for slide decks:

```csharp
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Core/Diagram/MermaidImageRenderer.cs)
- Currently supports **flowchart syntax** only, with sequence diagram support planned ([`SequenceLayout.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SequenceLayout.cs) exists but is not yet integrated)
- Integrates with both **Word** ([`WordHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Add.Diagram.cs)) and **PowerPoint** ([`PowerPointHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Core/Diagram/MermaidParser.cs). While [`Core/Diagram/SequenceLayout.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.