Technical presentations with Marp and Mermaid

Alexander Harris — Tue, 22 Aug 2023 09:51:26 +0000

I recently started learning to use 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 on customizing Marp where it explained how to integrate Mermaid 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 as my editor
I added the Marp for VS Code 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 plugin to enable Mermaid diagram previews in the Marp preview.
I also installed the 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:

<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

---
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

Writing to a remote file without vi / nano

Alexander Harris — Mon, 07 Aug 2023 08:27:00 +0000

If you ever need to quickly paste contents into a file via a shell on linux etc. but don't have a text editor installed (limited distro, jump box etc.) you can use the following command:

cat > myfile.txt << EOF
some test pasted from the cli
pboard including
newlines etc
EOF