Using reveal-md to create technical presentations

This post is a departure from the previous ones as it is describing a tool unrelated to the construction of this blog. But please, read on, as it might be useful if you’re in search of a developer tool to create quality technical presentations.

An unprepared presentation

2 years ago, I went to an international event for my company and heard that I was supposed to present some slides about technical updates concerning our team’s project. Except… I did not have prepared anything.

via GIPHY

So I bet on a cool tool I had previously tried out of a professional context: reveal-md.

It totally helped me focus on the slides’ content using great presentation and animation defaults. During the morning boring managers meeting, I managed (sic) to put up a nice set of slides with code samples, emojis, images. On the plus side, it kept me awake , or else I would have fallen asleep! 2 hours later I said “Sure, I can show you my slides!” and I delivered a solid presentation given the constraints.

via GIPHY

Since that time, all my presentations are made with reveal-md:

• I can quickly write in Markdown using any text editor
• I can animate with fragments
• I can embed GIFs, videos, images
• I can embed code snippets
• I can embed HTML, like real code or IFRAME showing live running examples
• …and I can use emojis

On that last point, and that will be the focus of another post, I had an issue as emoji support depends on the OS and browser. So, when I exported to PDF, the emojis were broken, and the same thing for my Windows 7 co-workers.

What is reveal-md?

Reveal-md tagline is:

reveal.js on steroids! Get beautiful reveal.js presentations from any Markdown file

Damn, what is reveal.js?

Just experience it yourself to feel it better than reading about it

Have you clicked the link above? No? click it. Navigate the slides. How smooth.

via GIPHY

So reveal-md is a special assembly of RevealJS with lots of useful plugins, which is readily usable and expects usage of Markdown to create presentations, instead of HTML.

---

Why I love it

Here is a non-exhaustive list of the things I found practical and easy to use to deliver impactful presentations with reveal-md:

1. fragments to slowly make pieces of a slide appear.
2. vertical and horizontal navigation
3. keyboard and mouse shortcuts
4. iframes, to embed live sites
5. code snippets
6. themes
7. exporting to PDF
8. exporting to a static website

---

fragments

To — wait for it… — reveal the content piece by piece, for example, if you want to avoid showing all your slide content in one go, you can use fragments:

![My awesome image](lame_image.gif)
<!-- .element: class="fragment" -->

via GIPHY

Slide navigation

Slides left-right and up-down navigation with ’---’ or ’----’

via GIPHY

useful shortcuts

There are some keyboard shortcuts, of which I particularly appreciate:

• Overview mode: “O” to see a birds-eye view of your presentation, “ESC” to return to the highlighted slide (you can quickly navigate with arrows)
• Fullscreen: “F”, “ESC” to exit fullscreen mode
• Speaker mode: “S” it synchronizes 2 windows: one with the presentation, and another with a timer and all speaker notes!
• Zoom-in: ALT+click make the view zoom at the position of your mouse’s pointer; very useful to look closely at a picture or chart surrounded by too much bullet points.

iframes

I use embedded iframes to show other websites, like caniuse.com:

---

## Can I Use CORS?

<iframe title="can i use cors" frameborder="0" width="100%" height="500pt" src="https://caniuse.com/cors/embed/description&links"></iframe>

---

Want to make it even better?

via GIPHY

You can add lazy-loading to the iframe just by using data-src instead of src. This way reveal will load the iframe’s content only when you will show the slide during your presentation.

Code snippets

You can embed code snippets really easily with a block and the language:

```javascript
console.log('great!');
```

or

```java
System.out.println("never use System.out.println at home");
```

Sometimes, I have to add some styles for the code to be displayed nicely:

```java
System.out.println("never use System.out.println at home");
```
<!-- .element: class="fragment" style="font-size: 0.30em !important;" -->

Themes

You can use a lot of different built-in themes. See the link for the complete list; I tend to use the white theme for my presentations. But I can quickly switch theme at any time with the --theme [theme] command line option.

exporting to PDF

Exporting the PDF?

Yep, reveal-md can do that!

via GIPHY

I use these NPM scripts in the package.json of the presentation’s repository:

  ...
  "scripts": {
    ...
    "preexport:pdf": "cp presentation.md 2print.md && replace-in-file '/class="fragment"/g' ' ' 2print.md --isRegex",
    "export:pdf": "reveal-md 2print.md -w --css local.css --theme white --print presentation.pdf",
    "postexport:pdf": "rm 2print.md"
  },
 ...

As you can see, I use replace-in-file dependency to remove all fragments in order to only print one page per slide, or else, each fragment will be printed on a new page, simulating a page-by-page animation.

exporting to an HTML static website

You can also export your presentation to a statically rendered HTML snapshot of it.

via GIPHY

I use these NPM scripts in the package.json of the presentation’s repository:

  ...
  "scripts": {
    ...
    "export:site": "reveal-md presentation.md --css local.css --theme white --static _site",
    "postexport:site": "cp *.svg _site/ && cp *.png _site/ && cp *.jpg _site/ && cp *.mp4 _site/ && cp robots.txt _site/ && cp *.svg _site/_assets/ && cp *.png _site/_assets/ && cp *.jpg _site/_assets/",
 ...

Again, some post-processing to copy all images, videos as they were not copied by the export static option of reveal-md — I might have missed some option, tell me how can I do this more cleanly if you know how; I will really appreciate the help!

---

Conclusion

You’ve seen that reveal-md is a powerful tool to create technical presentations with code, iframes, animations, and emojis. It comes with useful shortcuts and commands to export to a static website and PDF to share after a meeting.

I hope you enjoyed this post, or if you have any feedback, drop me a message on Twitter!