Mermaid Integration

[patrickpiresdev]

Is there an integration with mermaid? Or is there another way of making flowcharts with a language that is markdown like?

[yhatt]

Marp has no built-in integrations for any diagrams like mermaid.js, but you can try to extend Marp engine via compatible markdown-it plugins via if you are using Marp CLI.

// engine.js
module.exports = ({ marp }) => marp.use(require('markdown-it-mermaid'))

marp --engine ./engine.js your-markdown.md

But even if could render, the diagram may not become a reliable one because mermaid.js will misdetect font size in Marp slide (inside SVG <foreignObject>), as pointed out in:

• Support the mermaid yhatt/marp#125 (comment)
• Add support for mermaidjs marp-core#139 (comment)
• Mermaid - Text out of the box #468 (comment)

That is still a blocker for mermaid integration for Marp Core.

The most reliable way to place a mermaid.js diagram to Marp slide is using Markdown snippet generated by mermaid.live. It puts a diagram as pre-rendered SVG image so there is no broken texts. You also can use another "Diagrams as a Service" like kroki, that covers many diagram libraries including mermaid.js.

Related

• Support the mermaid yhatt/marp#125 (comment)
• Add support for mermaidjs marp-core#139
• Mermaid support marp-vscode#191

[hongvvu]

Hi @yhatt if I have two custom package to load for example one is admonition, one is mermaid what syntax look like in my engine.js? I tried following, only render one diagram rendered successfully on my end

const { Marp } = require('@marp-team/marp-core')
const markdownItAdmon = require('markdown-it-admon')
const markdownItMermaid = require('markdown-it-mermaid')

module.exports = (opts) => new Marp(opts).use(markdownItAdmon)
module.exports = ({ marp }) => marp.use(markdownItMermaid)

any advice?

[yhatt]

Chain .use().

const markdownItAdmon = require('markdown-it-admon')
const markdownItMermaid = require('markdown-it-mermaid')

module.exports = ({ marp }) => marp.use(markdownItMermaid).use(markdownItAdmon)

Refer to https://github.com/markdown-it/markdown-it#plugins-load or https://github.com/marp-team/marp-cli#spec.

[hongvvu]

thank you so much

[yhatt]

I've made the basic plugin example to render various diagrams at
https://gist.github.com/yhatt/8931dd98769bcc1c5b4b92fd1234a190. It is powered by kroki.io for reliable rendering in Marp slide.

Currently we have no plan to integrate as the default feature of Marp to prevent wasting kroki.io instance by free riding.

[JamesLarkinWhite]

Please excuse my ignorance... I am using marp via VsCode and it i use it daily to document the Process in many DataScience Projects i am involved in.
Mermaid support would really complete my Workflow.

Could you explain to me, how i get this functionality in VsCode such that the images are also rendered when i export my presentation?`
Unfortunately i do not understand how i need to apply the plugin you describe above.

Could you give me some instructuins?

Thank you in advance

[yhatt]

Marp for VS Code has no ability to extend Marp engine due to security reason. VS Code extension (GUI interface) has designed for beginners like you, and we have to save from that beginners who do not know techinal details catch in the malicious trap that comes from extending the engine. See details in #164 (reply in thread):

Using customized Marp engine is powerful, but with great power comes great responsibility. For example, Marp extension might be used as an attack vector to steal some important data in your PC if enabled the engine customization by JS.

If you do not want to leave from VS Code, you just have to use Marp CLI in VS Code integrated terminal!

[pillsilly]

Marp for VS Code has no ability to extend Marp engine due to security reason. VS Code extension (GUI interface) has designed for beginners like you, and we have to save from that beginners who do not know techinal details catch in the malicious trap that comes from extending the engine. See details in #164 (reply in thread):

Using customized Marp engine is powerful, but with great power comes great responsibility. For example, Marp extension might be used as an attack vector to steal some important data in your PC if enabled the engine customization by JS.

If you do not want to leave from VS Code, you just have to use Marp CLI in VS Code integrated terminal!

Is it possible if I folk and add this plugin to marp vscode plugin for my own use? -- I haven't went through the code yet.
I mean, at least it's technically doable?

[droctothorpe]

@yhatt given the basic example that you linked, how would one go about setting a background color for the exported images?

[yhatt]

A one of solution is using inline style to <img> element.

-        return `<p><marp-auto-scaling data-downscale-only><img src="${entrypoint}${lang}/svg/${data}"/></marp-auto-scaling></p>`
+        return `<p><marp-auto-scaling data-downscale-only><img src="${entrypoint}${lang}/svg/${data}" style="background-color: white;"/></marp-auto-scaling></p>`

It seems that kroki has no option for setting a background color of the image. Refer to yuzutech/kroki#1281.

[droctothorpe]

Amazing. Thank you so much! Considering how useful this gist is, I wonder if it should be part of the official marp docs.

[kazumatu981]

FYI: I've released markdown-it-plugin on npm, embed kroki image.
@kazumatu981/markdown-it-kroki

[greyovo]

thanks a lot !!!

[droctothorpe]

Thank you!

[GuillaumeDesforges]

I wrote my own way to render mermaid diagrams without using kroki.

• I forked marp-cli to make it able to handle async engine.render: see Allow async engine.render in converter marp-cli#540
  • EDIT: it has now been merged and released! https://github.com/marp-team/marp-cli/releases/v3.2.1
• I wrote my own engine

class PostprocessMarpitEngine extends Marp {
    /*
    Custom Marp engine with async post-processing
    Useful for async rendering
    https://github.com/markdown-it/markdown-it/issues/248
    */
    constructor(options, postprocess) {
        super(options)
        this.postprocess = postprocess
    }

    withPostprocess(postprocess) {
        this.postprocess = postprocess
        return this
    }

    async render(markdown, env = {}) {
        const { html, css, comments } = super.render(markdown, env)
        if (this.postprocess) {
            return await this.postprocess(markdown, env, html, css, comments)
        }
        return { html, css, comments }
    }
}

• I wrote a markdown-it plugin to change the mermaid fenced blocks with a custom class

async function marpMermaidPlugin(md) {
    /* Render mermaid fenced code block to a placeholder for post-processing */

    // super fence block rule
    const { fence } = md.renderer.rules
    // final fence block rule
    md.renderer.rules.fence = (tokens, idx, options, env, self) => {
        const info = md.utils.unescapeAll(tokens[idx].info).trim()
        if (info) {
            const [_, lang, divOptions] = info.match(/(\w+)\s*(?:\{\s*(.+)\s*\})?/)
            if (lang == "mermaid") {
                const graphDefinition = tokens[idx].content
                return `<div class="__mermaid" ${divOptions}>${graphDefinition}</div>`
            }
        }

        return fence.call(self, tokens, idx, options, env, self)
    }
}

• I wrote async functions that render these divs with mermaid
  • note that it needs you to vendor mermaid.js to pass it to puppeteer

async function renderSvgMermaid(graphDefinition) {
    /*
    Render mermaid graph to svg using puppeteer
    */

    // don't forget to set PUPPETEER_EXECUTABLE_PATH
    const browser = await puppeteer.launch({
        headless: "new",
        ignoreHTTPSErrors: true,
        args: [
            "--no-sandbox",
            "--disable-setuid-sandbox",
            '--disable-gpu',
            '--full-memory-crash-report',
            '--unlimited-storage',
        ],
        // uncomment for advanced debugging
        // dumpio: true,
    })
    const page = await browser.newPage()
    page.on('console', (msg) => {
        console.log(msg.text())
    })
    // add container to page
    await page.evaluate(() => {
        const graphDiv = document.createElement("div")
        graphDiv.id = "graphDiv"
        document.body.appendChild(graphDiv)
    });
    // add mermaid script to page
    await page.addScriptTag({
        path: path.join(__dirname, "vendor/mermaid.min.js"),
    })
    // render graph
    const svg = await page.evaluate(async (graphDefinition) => {
        const { svg } = await mermaid.render("graphDiv", graphDefinition);
        return svg
    }, graphDefinition)
    await browser.close()
    return svg;
}

async function processMermaidDiv(div) {
    const graphDefinition = div.textContent
    const svg = await renderSvgMermaid(graphDefinition)
    div.innerHTML = svg
    div.children[0].setAttribute("width", "100%")
    div.children[0].setAttribute("height", "100%")
}

async function syncProcessMermaidDivs(mermaidDivs) {
    /* Process mermaid div, one at a time */
    for (let i = 0; i < mermaidDivs.length; i++) {
        const div = mermaidDivs[i]
        await processMermaidDiv(div)
        console.log(`${i + 1}/${mermaidDivs.length}`)
    }
}

• finally we can setup the config in marp.config.mjs

export default {
    engine: async (constructorOptions) =>
        new PostprocessMarpitEngine(constructorOptions)
            .use(marpMermaidPlugin)
            .withPostprocess(async (markdown, env, html, css, comments) => {
                // parse html to DOM
                const doc = new jsdom.JSDOM(html)
                // turn div elements with class "__mermaid" into processed svgs
                const mermaidDivs = doc.window.document.querySelectorAll("div.__mermaid")
                console.log(`Processing ${mermaidDivs.length} mermaid divs...`)
                await syncProcessMermaidDivs(mermaidDivs)
                const processedHtml = doc.window.document.documentElement.outerHTML
                return { html: processedHtml, css, comments }
            }),
}

see my whole config here: https://github.com/GuillaumeDesforges/git-teaching-material/tree/5204102acaca9385d6fc0fbf7fb4f859d77e1021/presentation

Unfortunately I cannot sandbox this still. It seems like the headless chromium instance crashes when trying to run mermaid without internet.

[GuillaumeDesforges]

@codingluke thanks for the appreciation 😄

The reason I used puppeteer is because... this is what mermaid-cli does 😉
See https://github.com/mermaid-js/mermaid-cli/blob/e169d116c207eaba685b9155359100b4b654fa0b/src/index.js#L232

[codingluke]

Ok, I totally see your point and it will be good enough for sure. In using mermaid-cli I can imagine that it could be easyer to maintain (dependabot).

Anyway, keep on hacking 🚀

[codingluke]

Very nice! it works :) I will now try to add a version where I do not have to copy mermaid.min.js but can maintain it with dependencies.

One other thing. I encountered the same bug like in kroki. yuzutech/kroki#1345. Does anybody know which font I should use?

[codingluke]

Mermaid Marp Plugin

edit: I just added a cache option so that the graph is only generated once per definition :D, removed some nesting and invalidate the cache

@GuillaumeDesforges This plugin is based on your code, mermaid-cli and temp.

Why to use the cli?

• I guess they put alot of thoughs into it to render mermaid as good as possible
• Easy upgrade through a package.
• No need for mermaid.min.js in a vendor folder.
• Using buit in options like render as png.

Available Options:

• width=80%
• align=center | left | rigth
• type=png | svg

```mermaid width=80% align=center type=svg
flowchart TD;
    Kontrollstrukturen---Verzweigungen
    Kontrollstrukturen---Schleifen
    subgraph verz [ ]
        Verzweigungen---if[if-Anweisung]
        if---ifels[if-else-Anweisung]
        Verzweigungen---switch[switch-Anweisung]
    end
    Schleifen---while[while-Anweisung]
    Schleifen---dowhile[do-while-Anweisung]
    Schleifen---for[for-Anweisung]
    style verz fill:#00A17020,stroke:#00A17080,stroke-width:2px
```

Live Example:

• async engine
• marp-mermaid-plugin
• The rendered Flowchart from above as PNG centered in marp

Files

import path from "path";
import { run } from "@mermaid-js/mermaid-cli";
import temp from "temp";
import fs from "fs/promises";
import jsdom from "jsdom";

temp.track();

let cache = {};
let cleanupInterval = 2; // minutes
let cleanupTreshold = 30; // minimum cache size
setInterval(() => {
  if (Object.keys(cache).length < cleanupTreshold) return;
  console.log("clear mermaid cache!");
  cache = {};
}, cleanupInterval * 60000);

export default async function marpMermaid(md) {
  const { fence } = md.renderer.rules; // super fence block rule
  md.renderer.rules.fence = (tokens, idx, options, env, self) => {
    const info = md.utils.unescapeAll(tokens[idx].info).trim();
    const graphDefinition = tokens[idx].content;
    const cssClassName = `mermaid-${idx}`;
    const [_, lang, userOptions] = info?.match(/(\w+)\s*(?:\s*(.+)\s*)?/) || {};
    if (lang !== "mermaid")
      return fence.call(self, tokens, idx, options, env, self);

    let opts = { width: "100%", type: "png", align: "center" };
    userOptions
      ?.replaceAll(" = ", "=")
      .split(" ")
      .forEach((pair) => {
        const [key, value] = pair.split("=");
        opts[key] = value;
      });
    return `
      <style>
        .${cssClassName} {
          text-align: ${opts.align};
        }
        .${cssClassName} img,
        .${cssClassName} svg {
          width: ${opts.width};
        }
      </style>
      <div class="__mermaid ${cssClassName}" 
           data-type="${opts.type}" 
           data-idx=${idx}>
        ${graphDefinition}
      </div>
    `;
  };
}
export async function postProcessor(_markdown, _env, html, css, comments) {
  const doc = new jsdom.JSDOM(html); // parse html to DOM
  const mermaidDivs = doc.window.document.querySelectorAll("div.__mermaid");
  for (const element of mermaidDivs) await processMermaidDivCli(element);
  const processedHtml = doc.window.document.documentElement.outerHTML;
  return { html: processedHtml, css, comments };
}

async function processMermaidDivCli(div) {
  const graphDefinition = div.textContent;
  const cacheKey = btoa(graphDefinition) + div.dataset.type;

  // Return cached Image
  if (cache[cacheKey]) {
    if (div.dataset.type === "png")
      div.innerHTML = `<img src="data:image/png;base64,${cache[cacheKey]}" alt="" />`;
    else div.innerHTML = cache[cacheKey];
    return;
  }

  const dirPath = await temp.mkdir("mermaid");
  let inputFile = path.join(dirPath, "input.mmd");
  let outputFile = path.join(dirPath, "output");
  await fs.writeFile(inputFile, graphDefinition);
  await run(inputFile, outputFile, {
    outputFormat: div.dataset.type || "png",
    puppeteerConfig: {
      headless: "new",
      args: [
        "--no-sandbox",
        "--disable-web-security",
        "--disable-features=IsolateOrigins,site-per-process",
        "--force-color-profile=srgb",
        "--font-render-hinting=none",
      ],
      ignoreHTTPSErrors: true,
    },
    parseMMDOptions: {
      viewport: { height: 600, width: 800, deviceScaleFactor: 2 },
    },
  });
  if (div.dataset.type === "png") {
    cache[cacheKey] = await fs.readFile(outputFile, {
      encoding: "base64",
    });
    div.innerHTML = `<img src="data:image/png;base64,${cache[cacheKey]}" alt="" />`;
  } else {
    cache[cacheKey] = await fs.readFile(outputFile);
    div.innerHTML = cache[cacheKey];
  }
}

Usage in a async engine

import { Marp } from "@marp-team/marp-core";
import marpMermaid, { postProcessor } from "./marp-mermaid-plugin.mjs";

/*
 * Custom Marp engine with async post-processing
 * Useful for async rendering
 * https://github.com/markdown-it/markdown-it/issues/248
 */
class PostprocessMarpitEngine extends Marp {
  constructor(options, postprocess) {
    super(options);
    this.postprocess = postprocess;
  }

  withPostprocess(postprocess) {
    this.postprocess = postprocess;
    return this;
  }

  async render(markdown, env = {}) {
    const { html, css, comments } = super.render(markdown, env);
    if (this.postprocess) {
      return await this.postprocess(markdown, env, html, css, comments);
    }
    return { html, css, comments };
  }
}

export default async (constructorOptions) => {
  return new PostprocessMarpitEngine(constructorOptions)
    .use(marpMermaid)
    .withPostprocess(postProcessor);
};

[codingluke]

with the cache it is very, very fast :)

[hakib]

Just to add another option to mix, I ended us using this snippet at the top of my markdown file:

<script src="https://unpkg.com/[email protected]/dist/pako_deflate.min.js" async></script>
<script>
document.addEventListener('DOMContentLoaded', function() {
    setTimeout(function() {
        Array.from(document.querySelectorAll('.language-mermaid')).map(function(pre) {
            const encoded = new TextEncoder('utf-8').encode(pre.textContent);
            const compressed = window.pako.deflate(encoded, { level: 9, to: 'string' });
            const urlencoded = btoa(compressed).replace(/\+/g, '-').replace(/\//g, '_');
            const url = `https://kroki.io/mermaid/svg/${urlencoded}`;
            const img = document.createElement('img');
            img.src = url;
            pre.replaceWith(img);
        });
    // Give marp some time to load itself etc...
    }, 1000);
});
</script>

I can then use code blocks tagged with mermaid to render diagrams (using kroki):

---

# Slide with diagram

This will render a `mermaid` diagram:

```mermaid
classDiagram
    class Container {
        __contains__()
    }

---

The main benefit with this approach is that I don't have to extend the engine in any way, I can just use if for individual decks that need it.

Hope you find it useful as well.

[hakib]

I've set it so show up after 1 second. So, with the 1s wait plus the time it takes to generate the image, should appear after ~2-3 seconds.

[codingluke]

I had a kroki implementation in place. The problems were:

1. Korki sometimes was offline
2. The font is cut of in Flow charts, which is ugly
3. In Github Actions sometimes the network to remote URLs was not permittet. Depending on the region the Action is performed. Very undeterministic. So I ended up in a local version. see this thread

The downside of my solution is the startup rendering time when having many diagramms. Fortunately they are cached.

[hakib]

Hi,
I have some of these issues too

The yuzutech/kroki#1345, which is ugly

I've seen it also and was unable to find a fix for it.

The downside of my solution is the startup rendering time when having many diagramms. Fortunately they are cached.

This does add some time to the startup (even though it's executed async) and I haven't taken the time to do it lazily. For me however it's fine because I usually end up producing a PDF anyways.

[codingluke]

even though it's executed async

The rendering is async yes. But the rendering of a single file in marp is in-sync, so it waits until the chart is rendered await. It would be wonderful to be able to render the diagrams async and update the slide when it is finished.
However, then it would be tricky to generate PDFs as it has to wait for the charts anyway. For the moment I can live with the startup delay. The best would be parallel marp slide rendering.

[daviddwlee84]

This works when I compile using marp --html my_slides.md

This also works Technical presentations with Marp and Mermaid - DEV Community

---
marp: true
theme: default
---
# Title Page

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true });
</script>
---
# Diagram
<div class="mermaid">
  graph LR;
  a --> b;
  b --> c;
  c --> a;
</div>

But both of these can't properly render on VSCode preview (with HTML enabled)

And allow insecure content