Technical presentations with Marp and Mermaid
Tags: markdown, marp, mermaid
Published: 2023-08-22 09:51:26

I recently started learning to use [Marp](https://github.com/marp-team/marp) to create presentations / slide decks using Markdown syntax. I've always liked Markdown as a writing format and was curious to try creating a presentation instead of PowerPoint.

One thing that I found challanging was dealing with diagrams, which I tend to use a lot of. Typically use my diagram tool of choice then take a screen snip, or export the digram as an image and embed in my presentation.

In PowerPoint, copy+paste support makes this workflow pretty straight forward but for Markdown documents I found organizing a set of images to include a bit annoying.

Then I was reading this excellent [blog post](https://chris-ayers.com/2023/03/31/customizing-marp#:~:text=Marp%20comes%20with%20three%20built,and%20a%20few%20inverted%20examples) on customizing Marp where it explained how to integrate [Mermaid](http://mermaid.js.org/) diagrams.

Mermaid is another tool that I'd seen recently used for embedded diagrams in github repo readme files and had also been wanting to experiment with.

I followed the steps outlined and was pretty easily able to integrate Mermaid with Marp and ended up writing my whole presentation with about 15 diagrams in one markdown file.

## Prerequisites / Tools
* I used [VS Code](https://code.visualstudio.com/) as my editor
* I added the [Marp for VS Code](https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode) plugin to enable Marp features.
  * Checked the `Markdown -> Marp: Enable Html` from the extension settings. This allows `html` elements / blocks in the source document. Without this they will be encoded and output as text and not treated as Html blocks.
* I added the [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) plugin to enable Mermaid diagram previews in the Marp preview.
* I also installed the [Marp-Cli](https://github.com/marp-team/marp-cli) so I could script document generation etc. if I wanted to, though this isn't required.

## Getting started
* Create a new mardown file for your presentation.
* Add the Marp frontmatter block

```
---
marp: true
theme: default
---
```

* Add the following script block anywere in your presentation to pull in and initilize Mermaid:

```javascript
<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true });
</script>
```

* Add a diagram to a slide

```
# My Slide
<div class="mermaid">
  graph LR;
  a --> b;
  b --> c;
  c --> a;
</div>
```

* Use the `Markdown: Open Locked Preview to the Side` command from the `CTRL + SHIFT + P` actions menu to open the live preview of the document.
  * Click the `Some content has been disabled in this document` popup in the top right and then select `Allow Insecure Content` to enable Mermaid in the preview.
* Use the `Marp: Export Slide Deck...` command from the `CTRL + SHIFT + P` actions menu to export your slide deck.

## Gotchas / Limitations
I found a couple of rough edges still:
* I needed to add an empty line after the closing `</div>` tag of my mermaid diagrams or the formatting failed.
* I needed to remove any empty lines between elements in my Mermaid diagrams or they didn't render on export (though the preview was fine)
* The Mermaid diagrams in PDF export didn't size nodes correctly.

## Complete Example
```markdown
---
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>

---
# Next slide
* Some
* text
```


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/63g8exhpzfwi24lzde7d.png)