@benjilegnard/reveal.js-mermaid-plugin 0.2.0

package/README.md

@@ -0,0 +1,81 @@
+# @benjilegnard/reveal.js-mermaid-plugin
+
+This is a [reveal.js](https://revealjs.com/) plugin to render [mermaid](http://mermaid.ai) diagrams.
+
+Its main goal is to have modern ESM support for mermaid, allow you to embed any mermaid version (>=10), and use internal reveal.js types for typed configuration.
+
+## Demo
+
+Visible on <https://benjilegnard.github.io/reveal.js-mermaid-plugin/>
+
+## Installation
+
+```sh
+npm i @benjilegnard/reveal.js-mermaid-plugin mermaid reveal.js
+```
+
+`mermaid` (>= 10) and `reveal.js` (>= 6) are peer dependencies.
+
+## Usage
+
+Register the plugin **after** `Markdown` and **before** `Highlight`: it needs the
+markdown to be converted, and must replace the code blocks before highlight.js
+processes them.
+
+```ts
+import Reveal from "reveal.js";
+import Markdown from "reveal.js/plugin/markdown";
+import Highlight from "reveal.js/plugin/highlight";
+import Mermaid from "@benjilegnard/reveal.js-mermaid-plugin";
+
+const deck = new Reveal({
+  plugins: [Markdown, Mermaid, Highlight],
+});
+
+deck.initialize({
+  // passed as is to mermaid.initialize()
+  mermaid: {
+    theme: "dark",
+    // ... pass here any mermaid configuration
+  },
+});
+```
+
+Then write mermaid code blocks in your markdown slides:
+
+````md
+```mermaid
+flowchart LR
+  A --> B
+```
+````
+
+Each block is replaced by a `<div class="mermaid">` containing the inline SVG.
+If a diagram fails to render, the error is logged in the console, the source
+stays visible and its `<pre>` gets a `mermaid-error` class.
+
+Without the Markdown plugin, you just need to have html `<pre>`+`<code>` blocks:
+
+```html
+<pre>
+  <code class="mermaid">
+    flowchart LR
+      A --> B
+  </code>
+</pre>
+```
+
+## TypeScript
+
+Importing the plugin augments the reveal.js `RevealConfig` interface with a typed
+`mermaid` key (`MermaidConfig` from mermaid), so `deck.initialize({ mermaid: ... })`
+is type checked.
+
+`reveal.js` type definitions use extensionless relative imports: they only resolve
+with `"moduleResolution": "bundler"` (the Vite default). With `node16`/`nodenext`,
+`RevealConfig` resolves to `any` and no option is checked.
+
+## Alternatives
+
+- <https://github.com/zjffun/reveal.js-mermaid-plugin> : (embeds an hard-coded old version of mermaidjs)
+- <https://github.com/ludwick/reveal.js-mermaid-plugin> : (retired)

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import type { RevealPlugin } from "reveal.js";
+import { type MermaidConfig } from "mermaid";
+/**
+ * Options of the plugin, set with the `mermaid` key of the reveal.js config.
+ * Passed as is to `mermaid.initialize()`.
+ */
+export type MermaidPluginConfig = MermaidConfig;
+export interface MermaidPlugin extends RevealPlugin {
+    id: "mermaid";
+}
+declare module "reveal.js" {
+    interface RevealConfig {
+        /**
+         * Mermaid plugin configuration
+         *
+         * @see {@link https://mermaid.js.org/config/schema-docs/config.html}
+         */
+        mermaid?: MermaidPluginConfig;
+    }
+}
+/**
+ * Renders ```mermaid code blocks produced by the markdown plugin
+ * (marked outputs them as <pre><code class="mermaid">) into inline SVG.
+ *
+ * Must be registered after Markdown and before Highlight, so it runs once
+ * slides are converted and before highlight.js touches the code blocks.
+ */
+declare const Mermaid: () => MermaidPlugin;
+export default Mermaid;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,WAAW,CAAC;AACzD,OAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAEtD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,aAAa,CAAC;AAEhD,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,EAAE,EAAE,SAAS,CAAC;CACf;AAED,OAAO,QAAQ,WAAW,CAAC;IACzB,UAAU,YAAY;QACpB;;;;WAIG;QACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;KAC/B;CACF;AAED;;;;;;GAMG;AACH,QAAA,MAAM,OAAO,QAAO,aAkClB,CAAC;eAEY,OAAO"}

package/dist/index.js

@@ -0,0 +1,36 @@
+import mermaid, {} from "mermaid";
+/**
+ * Renders ```mermaid code blocks produced by the markdown plugin
+ * (marked outputs them as <pre><code class="mermaid">) into inline SVG.
+ *
+ * Must be registered after Markdown and before Highlight, so it runs once
+ * slides are converted and before highlight.js touches the code blocks.
+ */
+const Mermaid = () => ({
+    id: "mermaid",
+    async init(deck) {
+        mermaid.initialize({ startOnLoad: false, ...deck.getConfig().mermaid });
+        const blocks = deck
+            .getRevealElement()
+            ?.querySelectorAll("pre > code.mermaid, pre > code.language-mermaid") ?? [];
+        let index = 0;
+        for (const code of blocks) {
+            const pre = code.parentElement;
+            const container = document.createElement("div");
+            container.classList.add("mermaid");
+            try {
+                const { svg, bindFunctions } = await mermaid.render(`reveal-mermaid-${index++}`, code.textContent ?? "");
+                container.innerHTML = svg;
+                pre.replaceWith(container);
+                bindFunctions?.(container);
+            }
+            catch (error) {
+                // Keep the source visible so the error is easy to spot on the slide
+                console.error("[mermaid] failed to render diagram", error);
+                pre.classList.add("mermaid-error");
+            }
+        }
+    },
+});
+export default Mermaid;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,EAAE,EAAsB,MAAM,SAAS,CAAC;AAuBtD;;;;;;GAMG;AACH,MAAM,OAAO,GAAG,GAAkB,EAAE,CAAC,CAAC;IACpC,EAAE,EAAE,SAAS;IAEb,KAAK,CAAC,IAAI,CAAC,IAAe;QACxB,OAAO,CAAC,UAAU,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QAExE,MAAM,MAAM,GACV,IAAI;aACD,gBAAgB,EAAE;YACnB,EAAE,gBAAgB,CAChB,iDAAiD,CAClD,IAAI,EAAE,CAAC;QAEZ,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;YAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,aAAc,CAAC;YAChC,MAAM,SAAS,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;YAChD,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAEnC,IAAI,CAAC;gBACH,MAAM,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,MAAM,OAAO,CAAC,MAAM,CACjD,kBAAkB,KAAK,EAAE,EAAE,EAC3B,IAAI,CAAC,WAAW,IAAI,EAAE,CACvB,CAAC;gBACF,SAAS,CAAC,SAAS,GAAG,GAAG,CAAC;gBAC1B,GAAG,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;gBAC3B,aAAa,EAAE,CAAC,SAAS,CAAC,CAAC;YAC7B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,oEAAoE;gBACpE,OAAO,CAAC,KAAK,CAAC,oCAAoC,EAAE,KAAK,CAAC,CAAC;gBAC3D,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;YACrC,CAAC;QACH,CAAC;IACH,CAAC;CACF,CAAC,CAAC;AAEH,eAAe,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@benjilegnard/reveal.js-mermaid-plugin",
+  "version": "0.2.0",
+  "description": "reveal.js plugin rendering mermaid diagrams from code blocks as inline SVG",
+  "keywords": [
+    "diagram",
+    "markdown",
+    "mermaid",
+    "reveal.js",
+    "reveal.js-plugin",
+    "slides"
+  ],
+  "license": "MIT",
+  "author": "Benjamin Legrand",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "mermaid": "^12.0.0",
+    "reveal.js": "^6.0.2",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "mermaid": ">=10",
+    "reveal.js": ">=6"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "11.24.0",
+      "onFail": "download"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+import type { RevealApi, RevealPlugin } from "reveal.js";
+import mermaid, { type MermaidConfig } from "mermaid";
+
+/**
+ * Options of the plugin, set with the `mermaid` key of the reveal.js config.
+ * Passed as is to `mermaid.initialize()`.
+ */
+export type MermaidPluginConfig = MermaidConfig;
+
+export interface MermaidPlugin extends RevealPlugin {
+  id: "mermaid";
+}
+
+declare module "reveal.js" {
+  interface RevealConfig {
+    /**
+     * Mermaid plugin configuration
+     *
+     * @see {@link https://mermaid.js.org/config/schema-docs/config.html}
+     */
+    mermaid?: MermaidPluginConfig;
+  }
+}
+
+/**
+ * Renders ```mermaid code blocks produced by the markdown plugin
+ * (marked outputs them as <pre><code class="mermaid">) into inline SVG.
+ *
+ * Must be registered after Markdown and before Highlight, so it runs once
+ * slides are converted and before highlight.js touches the code blocks.
+ */
+const Mermaid = (): MermaidPlugin => ({
+  id: "mermaid",
+
+  async init(deck: RevealApi) {
+    mermaid.initialize({ startOnLoad: false, ...deck.getConfig().mermaid });
+
+    const blocks =
+      deck
+        .getRevealElement()
+        ?.querySelectorAll<HTMLElement>(
+          "pre > code.mermaid, pre > code.language-mermaid",
+        ) ?? [];
+
+    let index = 0;
+    for (const code of blocks) {
+      const pre = code.parentElement!;
+      const container = document.createElement("div");
+      container.classList.add("mermaid");
+
+      try {
+        const { svg, bindFunctions } = await mermaid.render(
+          `reveal-mermaid-${index++}`,
+          code.textContent ?? "",
+        );
+        container.innerHTML = svg;
+        pre.replaceWith(container);
+        bindFunctions?.(container);
+      } catch (error) {
+        // Keep the source visible so the error is easy to spot on the slide
+        console.error("[mermaid] failed to render diagram", error);
+        pre.classList.add("mermaid-error");
+      }
+    }
+  },
+});
+
+export default Mermaid;