mermaid-sequence-excel

Convert Mermaid sequenceDiagram scripts into editable Excel worksheets.

This package does not render Mermaid as an image. It parses the sequence diagram and writes a Mermaid-like worksheet with styled cells for participants, notes, frames, activation bars, and lifelines. Message arrows are injected as editable Excel drawing objects in the .xlsx package, so Microsoft Excel is not required at generation time.

Install

npm install mermaid-sequence-excel

Usage

From the command line:

npx mermaid-sequence-excel checkout.md
npx mermaid-sequence-excel checkout.md -o checkout-flow.xlsx
npx mermaid-sequence-excel checkout.md checkout-flow.xlsx
npx mermaid-sequence-excel checkout.mmd --title "Checkout Flow"

Markdown input can contain a Mermaid fence:

# Checkout flow

```mermaid
sequenceDiagram
actor User
participant API
User->>API: Create order
API->>API: Validate request
API-->>User: Done
```

If --output is omitted, the CLI writes an .xlsx file next to the input file.

CLI options:

mermaid-sequence-excel <input.md|input.mmd> [options]
mermaid-sequence-excel <input.md|input.mmd> <output.xlsx>

-o, --output <file>          Output xlsx path
    --title <text>           Worksheet title
    --worksheet-name <name>  Diagram worksheet name
    --no-source              Do not include the Source sheet
    --no-parsed              Do not include the Parsed sheet
    --no-warnings            Do not include the Warnings sheet

As a library:

import { writeSequenceDiagramXlsxFile } from 'mermaid-sequence-excel';

const source = `sequenceDiagram
title Checkout API flow
actor User
participant Web as Web App
participant API as API Server

User->>Web: Click checkout
Web->>+API: POST /orders
API-->>-Web: Order created
Web-->>User: Show receipt`;

await writeSequenceDiagramXlsxFile(source, './checkout-flow.xlsx');

Browser download:

import { writeSequenceDiagramXlsxBlob } from 'mermaid-sequence-excel';

const blob = await writeSequenceDiagramXlsxBlob(source);
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'sequence-diagram.xlsx';
a.click();
URL.revokeObjectURL(url);

Use with an existing ExcelJS workbook:

import ExcelJS from 'exceljs';
import {
  addSequenceDiagramWorksheet,
  writeWorkbookWithSequenceDrawingsFile,
} from 'mermaid-sequence-excel';

const workbook = new ExcelJS.Workbook();
const { diagram, worksheet } = addSequenceDiagramWorksheet(workbook, source, {
  worksheetName: 'Flow',
  includeParsedSheet: true,
  includeSourceSheet: true,
  includeWarningsSheet: true,
});

console.log(diagram.participants.length, worksheet.name);
await writeWorkbookWithSequenceDrawingsFile(workbook, './flow.xlsx');

workbook.xlsx.writeFile() will only write the cell layout. Use writeWorkbookWithSequenceDrawingsFile() or writeWorkbookWithSequenceDrawingsBuffer() when you need the arrow drawing objects.

Supported Mermaid syntax

• sequenceDiagram
• title
• autonumber
• participant, actor, create participant
• Messages: ->, -->, ->>, -->>, -x, --x, -), --)
• Self messages such as A->>A: refresh are rendered with a circular arrow shape.
• Activation markers: activate, deactivate, destroy, ->>+, -->>-
• Notes: Note left of, Note right of, Note over
• Blocks: loop, alt, else, opt, par, and, critical, break, rect, box, end

Unsupported lines are preserved as warning rows in the Excel sheet and surfaced in diagram.warnings.

API

parseSequenceDiagram(source): ParsedSequenceDiagram
addSequenceDiagramWorksheet(workbook, source, options?): SequenceWorksheetResult
createSequenceDiagramWorkbook(source, options?): Promise<SequenceWorkbookResult>
writeSequenceDiagramXlsxBuffer(source, options?): Promise<ArrayBuffer>
writeSequenceDiagramXlsxBlob(source, options?): Promise<Blob>
writeSequenceDiagramXlsxFile(source, outputPath, options?): Promise<ParsedSequenceDiagram>
writeWorkbookWithSequenceDrawingsBuffer(workbook): Promise<ArrayBuffer>
writeWorkbookWithSequenceDrawingsFile(workbook, outputPath): Promise<void>

Options:

interface SequenceExcelOptions {
  worksheetName?: string;
  parsedWorksheetName?: string;
  sourceWorksheetName?: string;
  warningsWorksheetName?: string;
  title?: string;
  includeParsedSheet?: boolean;
  includeSourceSheet?: boolean;
  includeWarningsSheet?: boolean;
}

By default, generated workbooks include Diagram, Parsed, Source, and Warnings sheets.

Publish

npm run build
npm test
npm publish --access public