README

This Flow package provides a small service and CLI commands to render Mermaid diagrams (https://mermaid.js.org/) to SVG using mermaid-cli (mmdc) with a Puppeteer configuration that can be controlled from Flow Settings.

Features

Render Mermaid definitions from files to SVG
Programmatic rendering service for inline Mermaid strings
CLI helper to bootstrap node dependencies and the headless browser
Stores a Puppeteer config JSON under Data/Temporary/Mermaid/ for reproducible runs

Prerequisites

Node.js and npm installed on the host where Flow runs
Network access to install npm packages on first setup
A Chromium/Chrome executable suitable for headless use
- The package can install chrome-headless-shell via Puppeteer (recommended for portability)

Installation

Ensure the package is available in your Flow distribution (DistributionPackages/fucodo.mermaid) and that composer autoload is up to date.
Run the install command to fetch node dependencies and a headless browser: ./flow mermaid:install This performs, inside the package directory:
- npm install
- npx puppeteer browsers install chrome-headless-shell

Configuration

The package reads its Puppeteer configuration from Flow settings and writes it to Data/Temporary/Mermaid/puppeteer-config.json before each render.

Default settings (Configuration/Settings.yaml in this package):

fucodo:
  mermaid:
    # is written in the puppeteer config file to guide mermaid to the correct location of the browser
    puppeteer-config:
      executablePath: '/usr/bin/chromium'
      args: ['--no-sandbox']

Override in your project’s Configuration/Settings.yaml as needed. Common options:

executablePath: absolute path to the Chromium/Chrome binary or chrome-headless-shell installed by Puppeteer
args: array of Chromium flags, e.g. ['--no-sandbox', '--disable-gpu']

Usage

CLI rendering from a Mermaid file to SVG (stdout):

Render file: ./flow mermaid:render /absolute/path/to/diagram.mmd > diagram.svg

Programmatic rendering in PHP (e.g., in a Flow controller/service):

use fucodo\mermaid\Service\MermaidService;
use Neos\Flow\Annotations as Flow;

class MyService {
    /**
     * @Flow\Inject
     * @var MermaidService
     */
    protected $mermaidService;

    public function buildSvg(): string
    {
        $mermaid = "graph TD; A-->B; A-->C; B-->D; C-->D;";
        return $this->mermaidService->renderMermaidGraph($mermaid);
    }
}

Commands

mermaid:install Fetches npm dependencies for mermaid-cli and installs a Chromium variant via Puppeteer that mmdc can drive. Run this after deployment or if dependencies changed.
mermaid:render Reads the Mermaid source from and writes the resulting SVG to stdout.

How it works

MermaidService prepares a Puppeteer config JSON at Data/Temporary/Mermaid/puppeteer-config.json using the fucodo.mermaid.puppeteer-config settings.
It invokes mermaid-cli (mmdc) located in this package’s node_modules, using: {PackagePath}/node_modules/.bin/mmdc --puppeteerConfigFile {config} -e svg -o {tmpOutput} < {input}
Output is an SVG string read from the temporary file and returned/printed.

Tips and troubleshooting

If rendering fails with browser launch errors, ensure the configured executablePath exists and is executable, or re-run ./flow mermaid:install to install chrome-headless-shell and then point executablePath to it.
On Linux containers, you may need --no-sandbox in args. This is the default in the package settings.
Make sure the Flow process user can write to Data/Temporary/.
If mmdc is not found, re-run mermaid:install or ensure node_modules exists under the package directory.

Paths used by the package

Puppeteer config JSON: Data/Temporary/Mermaid/puppeteer-config.json
Temp input/output files: Data/Temporary/*

License

MIT

Credits

Uses mermaid-cli (https://github.com/mermaid-js/mermaid-cli)
Uses Puppeteer for headless Chromium
Integrates with Neos Flow

fucodo / mermaid

Maintainers

Details