A Case Study in Creating a Conference Presentation using Markdown

TLDR; using Marp and Pandoc I can write a report and presentation using Markdown, then add other tools to make it ‘pretty’.

I’m going to show you a case study in how I’m planning a presentation for conference.

Because I want to offer you an alternative to diving straight into a powerpoint presentation.

My process for creating slides

What I’ve been doing is:

create an evernote
make all my notes in there
rough out some of the notes as summary info to add to a slide
create rough slides
expand my notes so they are like a ‘paper’ to support the presentation

Then I’ll:

move on to the slides
tidy up the slides
practice the presentation
keep the ‘paper’ up to date

And all of this means jumping between a few tools and I don’t really like working with presentation tools.

I’ve been looking for an alternative that fits my workflow.

An alternative that fits my workflow

And I think I might have found it. And I can:

write everything in markdown
version control my text
keep the ‘slides’ and the ‘paper’ together in the same file
create a pdf of the paper - with ’embedded slides’ - without doing any exporting or editing
create a pdf of the slides - without any extra editing or maintenance

And now I think I’ve found a way of doing that - and of creating ’nicely formatted and professional slides as well’ - all without touching a presentation tool.

So let’s have a look.

The Making Notes Phase

I’m still in the making notes phase for this presentation.

I make notes on it and restructure it when I get an idea - sometimes that means waking up at 3 in the morning and sitting in the office to type up the ideas, but that’s how I work on presentations.

In my earlier workflow, I would just have a set of notes at this point. And I would create those by running my ’notes’ through pandoc to create a pdf.

With my new workflow. I already have:

a set of notes in Evernote
a pdf of the paper generated by Pandoc
a presentation (using Marp)

I could wing it tomorrow, if I had to.

This is a massive win.

I always like to be at the point that ‘I could do it tomorrow, if I had to’. But I’m never usually at that point so early in the preparation cycle.

What that means is that every iteration from now on is an improvement (hopefully).

I could wing it tomorrow!

So I have notes, and they look a bit like this:

---

# And I'm going to say that:

## "any software that I use to support my testing is a "Testing Tool"


<!--

So if I use Cucumber in my testing it becomes a "Testing Tool"

And you can argue about it all you want. It won't stop me 
using it, or misusing it (if you say its not a testing tool
and I use it in my testing).

-->

---

And when I say “they look a bit like this”, I mean “they look exactly like that”.

I copy and pasted the above from my notes.

And what you can see is:

a draft slide
slides a separated by ---
and my ‘paper’ inside the HTML comments

I would normally continue working like this, in Evernote and a text editor. Until it was time to create the slides.

I can create slides now!

By using Marp, I can save my notes to a text file.

The same text file that I would feed into pandoc.

And I can view my notes as a set of slides.

The reason I use  to delineate my ‘paper’ sections is because most Markdown processing tools ignore HTML comments.

Marp, ignores HTML comments and only displays the --- delineated parts as a set of slides.

Using Marp, I can:

view my notes as a set of slides
get a feel for my notes as a ‘presentation’
output a pdf that I could use to ‘wing it tomorrow’

The Marp slides output isn’t great, but it is certainly ‘good enough’, and I released the Java and Selenium Install Checklists to slideshare using Marp, directly from the checklist file that I maintain on github:

Same source document different rendering.

The PDF isn’t ‘perfect’ but its good enough for my purposes.

I can view the paper easily!

If I copy and paste the contents of the file or evernote into dillinger.io

I can see a rough version of the paper, but Dillinger shows me the  which isn’t great, but for review purposes this is fine and easy.

I couldn’t use Dillinger to release the paper in that condition though.

I can create a pdf paper easily!

I use pandoc to create PDFs.
If you’ve hired me for consultancy work - pretty much guaranteed that the PDF report you received at the end was generated in pandoc.

Trade Secret - I can create a report really quickly because:

I write it as I consult

When I make my notes in Evernote

I write in Markdown

I convert with Pandoc

I spend time at the end of the day (/trip back on the plane/journey back on the train/engagement in the airport lounge) editing and fixing spelling errors

generate in Pandoc - I tend not to spend much time reformatting

Shh, keep that a secret though, I don’t want my competitors to have the same advantages that I have.

Normally I just run a text file through pandoc:

pandoc mynotes.txt -f markdown -o professional_report.pdf

(pandoc can change page size and create a table of contents and output MS Word and OpenOffice files, but somethings I’ll keep as trade secrets.)

But pandoc would ignore the HTML comments as well, so I create a script:

(Get-Content slides.txt) | 
ForEach-Object { $_ -replace "<!--" , "-----" } | 
ForEach-Object { $_ -replace "-->","------" } | 
Set-Content slides.md
pandoc slides.md -f markdown -o output.pdf

Above is windows powershell which converts the HTML comments into Markdown horizontal rules.

I converted an open comment  to six ------ to give me the option of ‘find and replacing’ the report back into a slide deck if I want to.

If I was on mac I’d probably create a .sh that used sed to perform the find and replace operation.

This gives me a fairly nicely formatted pdf.