Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

A Case Study in Creating a Conference Presentation Using Markdown

DZone's Guide to

A Case Study in Creating a Conference Presentation Using Markdown

Using Marp and Pandoc, I can write a report and a presentation using Markdown, and then add other tools to make it look more pretty.

· Agile Zone
Free Resource

See how three solutions work together to help your teams have the tools they need to deliver quality software quickly. Brought to you in partnership with CA Technologies

I’m going to show you a case study in how I’m planning a presentation for a 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 information 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.
All of this means jumping between a few tools. 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

I think I might have found it. 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, 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. This example is my presentation for TestBash Netherlands in January 2017. 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 where 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 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 <!-- and --> 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 it's 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 <!-- and --> , which isn’t great. 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, it's 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.
  • I 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 some things 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 five minus signs -----and close --> 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.
Good enough. It makes it easy for me to see contents, slides, summaries, and details. The main point for me is that I get this with no extra effort. I can imagine that to release the paper, I would convert the comments to "" and avoid having extra horizontal lines. 
But for the moment, I’m comfortable with the double lines, and the removal of comments is a one-way operation.

Version Control Benefits

A great benefit from this is that the only things I need to version control now are a single text file, a conversion script, and any images. I don’t need to add a huge LibreOffice or Powerpoint presentation. And I have proper versioning, so I can diff the notes and slides and I can bring back lost information.

But It Ain’t That Pretty at All

I’m not that bothered about the prettiness. Normally, I prettify the slides close to the release date, anyway.

But We Can Automate It All!

I’m currently evaluating Deckset, a Mac-only app that can take my notes file with the slides and the HTML-embedded paper and can format it into something pretty:


I just have to choose a template, pick the colors, and then tweak the Markdown to make it work better as a slide deck.

Next Year

I guess we’ll see in January 2017 how I actually create the slides. And we’ll see which of the above slides actually make it from the Notes phase, into the Finalize Slidedeck phase.

Bonus video showing the tools in action (available on YouTube).

Discover how TDM Is Essential To Achieving Quality At Speed For Agile, DevOps, And Continuous Delivery. Brought to you in partnership with CA Technologies

Topics:
markdown ,pandoc ,agile ,presentations

Published at DZone with permission of Alan Richardson, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

THE DZONE NEWSLETTER

Dev Resources & Solutions Straight to Your Inbox

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

X

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}