mermaid-to-excalidraw-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# mermaid-to-excalidraw-cli
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![GitHub issues](https://img.shields.io/github/issues/ayurkin/mermaid-to-excalidraw-cli)](https://github.com/ayurkin/mermaid-to-excalidraw-cli/issues)
+
+Convert Mermaid (`.mmd`) diagrams into Excalidraw (`.excalidraw`) using a headless Chromium runtime for accurate layout and text metrics.
+
+## Why
+
+- Mermaid is easy to edit as text.
+- Excalidraw is great for visual docs and hand edits.
+- This tool keeps Mermaid as the source of truth while generating readable Excalidraw output.
+
+## Features
+
+- High-fidelity conversion using real browser rendering (Playwright + Chromium)
+- Converts single files or entire folders (recursive)
+- Deterministic output suitable for version control
+
+## Install
+
+```bash
+npm install
+npx playwright install chromium
+```
+
+For global usage:
+
+```bash
+npm link
+```
+
+After publishing to npm:
+
+```bash
+npm install -g mermaid-to-excalidraw-cli
+```
+
+## Usage
+
+```bash
+mmd2excalidraw <input> [output]
+```
+
+### Examples
+
+```bash
+# Convert a single file
+mmd2excalidraw docs/architecture/service-overview.mmd
+
+# Convert all .mmd files in a directory (recursive)
+mmd2excalidraw docs/architecture
+
+# Convert directory and write outputs to a separate folder
+mmd2excalidraw docs/architecture -o docs/architecture
+```
+
+## Options
+
+- `--font-size <number>`: Mermaid font size (default: 16)
+- `--curve <linear|basis>`: Flowchart curve style (default: linear)
+- `--max-edges <number>`: Max edges (default: 500)
+- `--max-text-size <number>`: Max text size (default: 50000)
+- `-o, --output <path>`: Output file or directory
+- `-h, --help`: Show help
+
+## Output
+
+The CLI writes Excalidraw scene JSON with both shapes and text elements, ready to open in Excalidraw or the VS Code extension.
+
+## Troubleshooting
+
+- **Playwright error / Chromium missing**
+  Run `npx playwright install chromium`.
+
+- **Conversion hangs**
+  Ensure no firewall blocks local loopback access.
+
+## Development
+
+```bash
+node bin/mmd2excalidraw.mjs --help
+```
+
+## Publish
+
+1. Update `version` in `package.json`
+2. `npm publish`
+
+## License
+
+MIT
+
+## Credits
+
+This CLI is built on top of the official Excalidraw Mermaid converter:
+https://github.com/excalidraw/mermaid-to-excalidraw

package/bin/mmd2excalidraw.mjs

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import http from "node:http";
+import { fileURLToPath } from "node:url";
+import { chromium } from "playwright";
+
+const DEFAULTS = {
+  fontSize: 16,
+  curve: "linear",
+  maxEdges: 500,
+  maxTextSize: 50000,
+};
+
+function printHelp() {
+  const helpText = `Usage:
+  mmd2excalidraw <input> [output]
+
+Options:
+  -o, --output <path>       Output file or directory
+  --font-size <number>      Mermaid font size (default: ${DEFAULTS.fontSize})
+  --curve <linear|basis>    Mermaid flowchart curve (default: ${DEFAULTS.curve})
+  --max-edges <number>      Max edges (default: ${DEFAULTS.maxEdges})
+  --max-text-size <number>  Max text size (default: ${DEFAULTS.maxTextSize})
+  -h, --help                Show this help
+
+Notes:
+  Requires Playwright with Chromium installed:
+  npx playwright install chromium
+
+Examples:
+  mmd2excalidraw docs/architecture/service-overview.mmd
+  mmd2excalidraw docs/architecture -o docs/architecture
+`;
+  console.log(helpText);
+}
+
+function parseArgs(argv) {
+  const options = { ...DEFAULTS };
+  let output = null;
+  const positionals = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      printHelp();
+      process.exit(0);
+    }
+
+    if (arg === "-o" || arg === "--output") {
+      output = argv[i + 1];
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--font-size") {
+      options.fontSize = Number.parseInt(argv[i + 1], 10);
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--curve") {
+      options.curve = argv[i + 1] || DEFAULTS.curve;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--max-edges") {
+      options.maxEdges = Number.parseInt(argv[i + 1], 10);
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--max-text-size") {
+      options.maxTextSize = Number.parseInt(argv[i + 1], 10);
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    positionals.push(arg);
+  }
+
+  if (positionals.length === 0) {
+    printHelp();
+    throw new Error("Missing input path.");
+  }
+
+  return {
+    input: positionals[0],
+    output: output ?? positionals[1] ?? null,
+    options,
+  };
+}
+
+function getPackageRoot() {
+  const scriptPath = fileURLToPath(import.meta.url);
+  return path.resolve(path.dirname(scriptPath), "..");
+}
+
+function getContentType(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  switch (ext) {
+    case ".js":
+    case ".mjs":
+      return "text/javascript";
+    case ".css":
+      return "text/css";
+    case ".json":
+      return "application/json";
+    case ".svg":
+      return "image/svg+xml";
+    case ".map":
+      return "application/json";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+function createServer() {
+  const packageRoot = getPackageRoot();
+  const moduleRoots = new Map([
+    [
+      "/modules/mermaid-to-excalidraw/",
+      path.join(
+        packageRoot,
+        "node_modules",
+        "@excalidraw",
+        "mermaid-to-excalidraw",
+        "dist"
+      ),
+    ],
+    [
+      "/modules/mermaid/",
+      path.join(packageRoot, "node_modules", "mermaid", "dist"),
+    ],
+    [
+      "/modules/nanoid/",
+      path.join(packageRoot, "node_modules", "nanoid"),
+    ],
+    [
+      "/modules/markdown-to-text/",
+      path.join(packageRoot, "vendor", "markdown-to-text"),
+    ],
+    [
+      "/excalidraw/",
+      path.join(
+        packageRoot,
+        "node_modules",
+        "@excalidraw",
+        "excalidraw",
+        "dist"
+      ),
+    ],
+    [
+      "/react/",
+      path.join(packageRoot, "node_modules", "react", "umd"),
+    ],
+    [
+      "/react-dom/",
+      path.join(packageRoot, "node_modules", "react-dom", "umd"),
+    ],
+  ]);
+
+  const importMap = {
+    imports: {
+      mermaid: "/modules/mermaid/mermaid.esm.mjs",
+      nanoid: "/modules/nanoid/index.browser.js",
+      "@excalidraw/markdown-to-text":
+        "/modules/markdown-to-text/index.mjs",
+      "@excalidraw/mermaid-to-excalidraw":
+        "/modules/mermaid-to-excalidraw/index.js",
+    },
+  };
+
+  const html = `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <script type="importmap">${JSON.stringify(importMap)}</script>
+  <script src="/react/react.production.min.js"></script>
+  <script src="/react-dom/react-dom.production.min.js"></script>
+  <script src="/excalidraw/excalidraw.production.min.js"></script>
+  <script type="module">
+    import { parseMermaidToExcalidraw } from "@excalidraw/mermaid-to-excalidraw";
+    window.parseMermaidToExcalidraw = parseMermaidToExcalidraw;
+  </script>
+</head>
+<body></body>
+</html>`;
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url ?? "/", "http://localhost");
+      const pathname = url.pathname;
+
+      if (pathname === "/" || pathname === "/index.html") {
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(html);
+        return;
+      }
+
+      for (const [prefix, root] of moduleRoots.entries()) {
+        if (!pathname.startsWith(prefix)) {
+          continue;
+        }
+
+        const relativePath = pathname.slice(prefix.length);
+        const safePath = path
+          .normalize(relativePath)
+          .replace(/^([/\\]*\.\.)+/, "");
+        const filePath = path.join(root, safePath);
+        const stat = await fs.stat(filePath).catch(() => null);
+        if (!stat || !stat.isFile()) {
+          res.writeHead(404);
+          res.end("Not found");
+          return;
+        }
+
+        const fileBuffer = await fs.readFile(filePath);
+        res.writeHead(200, { "Content-Type": getContentType(filePath) });
+        res.end(fileBuffer);
+        return;
+      }
+
+      res.writeHead(404);
+      res.end("Not found");
+    } catch (error) {
+      res.writeHead(500);
+      res.end("Server error");
+      console.error(error);
+    }
+  });
+
+  return new Promise((resolve, reject) => {
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        reject(new Error("Failed to start server."));
+        return;
+      }
+      resolve({ server, url: `http://127.0.0.1:${address.port}` });
+    });
+  });
+}
+
+async function listMermaidFiles(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await listMermaidFiles(fullPath)));
+    } else if (entry.isFile() && entry.name.endsWith(".mmd")) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+async function resolveOutputPath(inputPath, outputPath) {
+  if (!outputPath) {
+    return inputPath.replace(/\.mmd$/, ".excalidraw");
+  }
+
+  try {
+    const stat = await fs.stat(outputPath);
+    if (stat.isDirectory()) {
+      return path.join(
+        outputPath,
+        path.basename(inputPath).replace(/\.mmd$/, ".excalidraw")
+      );
+    }
+  } catch {
+    // Output does not exist yet; treat as file path.
+  }
+
+  return outputPath;
+}
+
+async function convertMermaidFile(page, inputPath, outputPath, options) {
+  const mermaid = await fs.readFile(inputPath, "utf8");
+
+  const { elements, files } = await page.evaluate(
+    async ({ mermaidText, opts }) => {
+      const config = {
+        flowchart: { curve: opts.curve },
+        themeVariables: { fontSize: `${opts.fontSize}px` },
+        maxEdges: opts.maxEdges,
+        maxTextSize: opts.maxTextSize,
+      };
+
+      const { elements, files } = await window.parseMermaidToExcalidraw(
+        mermaidText,
+        config
+      );
+      const convertedElements = window.ExcalidrawLib.convertToExcalidrawElements(
+        elements,
+        { regenerateIds: false }
+      );
+      return { elements: convertedElements, files: files ?? {} };
+    },
+    { mermaidText: mermaid, opts: options }
+  );
+
+  const scene = {
+    type: "excalidraw",
+    version: 2,
+    source: "https://excalidraw.com",
+    elements,
+    appState: { viewBackgroundColor: "#ffffff" },
+    files: files ?? {},
+  };
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, JSON.stringify(scene, null, 2), "utf8");
+}
+
+async function run() {
+  const { input, output, options } = parseArgs(process.argv.slice(2));
+  const inputPath = path.resolve(process.cwd(), input);
+  const outputPath = output ? path.resolve(process.cwd(), output) : null;
+
+  const stats = await fs.stat(inputPath);
+  const { server, url } = await createServer();
+  const browser = await chromium.launch({ headless: true });
+  const page = await browser.newPage();
+  page.on("console", (msg) => {
+    console.log(`[browser:${msg.type()}] ${msg.text()}`);
+  });
+  page.on("pageerror", (error) => {
+    console.error(`[browser:error] ${error.message}`);
+  });
+  page.on("requestfailed", (request) => {
+    console.error(`[browser:requestfailed] ${request.url()} ${request.failure()?.errorText}`);
+  });
+
+  try {
+    await page.goto(url, { waitUntil: "load" });
+    await page.waitForFunction(
+      () =>
+        window.parseMermaidToExcalidraw &&
+        window.ExcalidrawLib?.convertToExcalidrawElements,
+      { timeout: 60000 }
+    );
+
+    if (stats.isDirectory()) {
+      const mermaidFiles = await listMermaidFiles(inputPath);
+      if (mermaidFiles.length === 0) {
+        console.log(`No .mmd files found under ${inputPath}`);
+        return;
+      }
+
+      for (const filePath of mermaidFiles) {
+        const relative = path.relative(inputPath, filePath);
+        const targetBase = outputPath ?? inputPath;
+        const targetPath = path
+          .join(targetBase, relative)
+          .replace(/\.mmd$/, ".excalidraw");
+        console.log(`Converting ${relative}`);
+        await convertMermaidFile(page, filePath, targetPath, options);
+      }
+      return;
+    }
+
+    if (!inputPath.endsWith(".mmd")) {
+      throw new Error("Input file must have .mmd extension.");
+    }
+
+    const finalOutput = await resolveOutputPath(inputPath, outputPath);
+    console.log(`Converting ${path.basename(inputPath)}`);
+    await convertMermaidFile(page, inputPath, finalOutput, options);
+  } finally {
+    await page.close();
+    await browser.close();
+    server.close();
+  }
+}
+
+run()
+  .then(() => process.exit(0))
+  .catch((error) => {
+    console.error(error.message || error);
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "mermaid-to-excalidraw-cli",
+  "version": "0.1.1",
+  "description": "Convert Mermaid (.mmd) to Excalidraw (.excalidraw) using headless Chromium.",
+  "license": "MIT",
+  "author": "Aleksandr Yurkin <alx.yurkin@gmail.com>",
+  "type": "module",
+  "bin": {
+    "mmd2excalidraw": "bin/mmd2excalidraw.mjs"
+  },
+  "scripts": {
+    "start": "node bin/mmd2excalidraw.mjs --help"
+  },
+  "files": [
+    "bin",
+    "vendor",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mermaid-to-excalidraw",
+    "mermaid",
+    "excalidraw",
+    "diagram",
+    "cli",
+    "converter"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/ayurkin/mermaid-to-excalidraw-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ayurkin/mermaid-to-excalidraw-cli/issues"
+  },
+  "homepage": "https://github.com/ayurkin/mermaid-to-excalidraw-cli",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@excalidraw/excalidraw": "0.17.1-7381-cdf6d3e",
+    "@excalidraw/mermaid-to-excalidraw": "1.1.4",
+    "playwright": "^1.50.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  }
+}

package/vendor/markdown-to-text/index.mjs

@@ -0,0 +1,80 @@
+export const removeMarkdown = (markdown, options = { listUnicodeChar: "" }) => {
+  options = options || {};
+  options.listUnicodeChar = Object.prototype.hasOwnProperty.call(
+    options,
+    "listUnicodeChar"
+  )
+    ? options.listUnicodeChar
+    : false;
+  options.stripListLeaders = Object.prototype.hasOwnProperty.call(
+    options,
+    "stripListLeaders"
+  )
+    ? options.stripListLeaders
+    : true;
+  options.gfm = Object.prototype.hasOwnProperty.call(options, "gfm")
+    ? options.gfm
+    : true;
+  options.useImgAltText = Object.prototype.hasOwnProperty.call(
+    options,
+    "useImgAltText"
+  )
+    ? options.useImgAltText
+    : true;
+  options.preserveLinks = Object.prototype.hasOwnProperty.call(
+    options,
+    "preserveLinks"
+  )
+    ? options.preserveLinks
+    : false;
+
+  let output = markdown || "";
+
+  output = output.replace(/^(-\s*?|\*\s*?|_\s*?){3,}\s*$/gm, "");
+
+  try {
+    if (options.stripListLeaders) {
+      if (options.listUnicodeChar) {
+        output = output.replace(
+          /^([\s\t]*)([\*\-\+]|\d+\.)\s+/gm,
+          `${options.listUnicodeChar} $1`
+        );
+      } else {
+        output = output.replace(/^([\s\t]*)([\*\-\+]|\d+\.)\s+/gm, "$1");
+      }
+    }
+    if (options.gfm) {
+      output = output
+        .replace(/\n={2,}/g, "\n")
+        .replace(/~{3}.*\n/g, "")
+        .replace(/~~/g, "")
+        .replace(/`{3}.*\n/g, "");
+    }
+    if (options.preserveLinks) {
+      output = output.replace(/\[(.*?)\][\[\(](.*?)[\]\)]/g, "$1 ($2)");
+    }
+    output = output
+      .replace(/<[^>]*>/g, "")
+      .replace(/^[=\-]{2,}\s*$/g, "")
+      .replace(/\[\^.+?\](\: .*?$)?/g, "")
+      .replace(/\s{0,2}\[.*?\]: .*?$/g, "")
+      .replace(/\!\[(.*?)\][\[\(].*?[\]\)]/g, options.useImgAltText ? "$1" : "")
+      .replace(/\[(.*?)\][\[\(].*?[\]\)]/g, "$1")
+      .replace(/^\s{0,3}>\s?/g, "")
+      .replace(/(^|\n)\s{0,3}>\s?/g, "\n\n")
+      .replace(/^\s{1,2}\[(.*?)\]: (\S+)( \".*?\")?\s*$/g, "")
+      .replace(
+        /^(\n)?\s{0,}#{1,6}\s+| {0,}(\n)?\s{0,}#{0,} {0,}(\n)?\s{0,}$/gm,
+        "$1$2$3"
+      )
+      .replace(/([\*_]{1,3})(\S.*?\S{0,1})\1/g, "$2")
+      .replace(/([\*_]{1,3})(\S.*?\S{0,1})\1/g, "$2")
+      .replace(/(`{3,})(.*?)\1/gm, "$2")
+      .replace(/`(.+?)`/g, "$1")
+      .replace(/\n{2,}/g, "\n\n");
+  } catch (error) {
+    console.error(error);
+    return markdown;
+  }
+  return output;
+};