Beautiful presentations from markdown — who knew it could be so easy?
I’ve recently been trying reveal-md as a front end for reveal.js to create presentations and been really impressed. I wanted to share my learnings and some useful tips in this blog article for others keen to do the same. If nothing else, my future self will be delighted for the reference material. :)
Markdown — really??
I’m a big fan of markdown and use it daily to structure and capture notes for work. It allows me to:
- quickly and easily create something that is easy to read,
- link to pictures and other “things” pertinent to what I’m capturing, and
- can easily be searched via the command line or from a browser or viewer.
(I use the Markdown Writer package for Atom and Markdown Viewer extension for Chrome.)
Recently, as an incentive to get down to work on a presentation I needed to create (yes, I know), I decided to try the reveal-md front end for reveal.js framework to create a presentation using markdown. It was a success!
My material is here: https://mandieq.github.io/opf_learnings and the code repository is here.
Getting up and running
Using a docker container is an option for reveal-md — which is actually a nice way to “suck it and see” and decide if I wanted commit to installing. I did find that I couldn’t get printing to work with the container though, and that was a deal breaker if I couldn’t export my presentation to a PDF. I needed that functionality both to share afterwards, but also as a backup in case reveal suddenly let me down on the day! (spoiler alert, it didn’t)
So I installed node.js using homebrew on my mac, and then installed reveal-md which pulled in all the good stuff needed underneath.
brew update
brew install node
npm install -g reveal-md`Useful things / formatting
The github page for reveal-md has some pretty decent documentation on the basics of creating slides and the structures (you can do so very cool things where you navigate downwards vs to the right), so I won’t repeat that here. But I did find my css / html was a bit rusty so I needed to dig around to remember how to create some effects.
Using parallax background — this was an effect I liked from the reveal.js documentation, but couldn’t see how to do for reveal-md. To create this effect with reveal-md, you need to include the following in a reveal.js options file called reveal.json that must be located at the root directory of the markdown file.
{
"parallaxBackgroundImage": "images/backdrop.png",
"parallaxBackgroundSize": "2000px 1125px"
}Additional css — can easily be added to the bottom of the markdown file in a style section if you want something easily changed for the presentation you are currently working on. I could certainly see benefit to having your own css if you have a load of cool effects you want to use regularly.
<style>
#bright {
color: deeppink;
}
</style>You can then use this with id for the specific element:
<span id='bright'>open</span>Two columns — easily added into the style section mentioned above.
#left {
margin: 10px 0 15px 20px;
text-align: center;
float: left;
z-index:-10;
width:48%;
font-size: 0.85em;
line-height: 1.5;
}#right {
margin: 10px 0 15px 0;
float: right;
text-align: center;
z-index:-10;
width:48%;
font-size: 0.85em;
line-height: 1.5;
}
Again, using id in the main body for structure.
<div id="left"></div><div id="right">#### Title
1. List
2. List
3. List</div>
Dark backgrounds behind titles — can be created in the markdown or added in the style section. Something like the following works within the markdown, remembering to leave a line between the div and the markdown otherwise it breaks it.
<div style="background-color: rgba(0, 0, 0, 0.9); color: #fff; padding: 20px;">Some markdown here with a dark background.</div>
Or in the style section:
#dark_back {
background-color: rgba(0, 0, 0, 0.9);
color: #fff;
padding: 20px;
}Left align and text sizing — (I know it is easy, but for reference):
<div style="font-size: 20px; text-align: left;">Left aligned dinky text here</div>
Image sizing — in case your images get too big and start taking over your slide.
 <!-- .element width="400px" -->Down arrow — to really highlight to yourself during a presentation (and the audience reviewing your whizzy material afterwards) that they need to hit the down button and not right button! With some additional code to hide the background that comes as default with the dark theme.
 <!-- .element style="border: 0; background: None; box-shadow: None" width="100px" -->Lots more out there — bear in mind that you can view the source of a page with most browsers. So if you see a presentation using this framework with an effect that you like? Have a look at the source and work out how it was done. Loads of example presentations are available.
Github for presentations? Genius!
One thing that really appealed to me with reveal was the ability to manage the code using github. It will allow me to work with others on the same material and also keep versions of my material remote from my laptop.
The bonus here is being able to use GitHub Pages to host the resulting presentation. In theory you could present from anyone’s computer using this feature — again a nice backup in case you managed to drop your laptop on the way to your session.
I took advantage of this by creating a static version of the presentation into a directory called docs — which can then be switched on as the source of GitHub Pages from the settings of your repository — very neat!
reveal-md presentation.md --static docsOne key thing I did notice with this was that the static version doesn’t copy across images which are used for backgrounds for some reason. So these needed to be copied across manually into the relevant place within the docs directory.
Final thoughts
Will I keep using this framework? I think there is a good chance I will for certain situations. I love being able to write my “story” in markdown without the distraction of PowerPoint and then finesse and add images and cool effects afterwards. I particularly like the native code formatting.
I’m not sure it would work well for all collaborative presentations unless the other contributors are all tech savvy and willing to install the relevant software on their own machines. But I can live in hope. :)
And finally, I enjoyed How to avoid death By PowerPoint, a Tedx talk by David JP Phillips — this kind of framework lends itself very nicely to following the guidelines he mentions!
