Online Tool Store
· 4 min read
How to Turn Markdown Notes Into a Slide Deck
Manesh Jayawardhana
CIO & Co-founder
You’ve got good notes. Structured headings, a few bullet lists, the numbers you want to quote. What you need is a deck, and the usual path is to open presentation software, create a blank slide, and start copying and pasting — losing an hour to text boxes that don’t align.
The notes were already the deck. They just needed splitting.
Why Markdown works as a source format
A presentation is a sequence of small pieces of structured text. So is a Markdown file. The mapping is nearly one to one: a heading starts a slide, the content under it is the slide body, and a horizontal rule is an explicit break.
Keeping the source as plain text has practical consequences beyond convenience. It diffs cleanly in version control, so you can see what changed between the version you gave last month and the one you’re giving tomorrow. It’s searchable. It doesn’t lock the content into one application’s file format. And it makes the deck’s structure — which is what actually matters — visible while you’re editing.
The trade-off is real: you’re giving up fine visual control. For a conference keynote with custom animation, that’s the wrong trade. For an internal presentation, a workshop, or a talk where the argument matters more than the transitions, it’s the right one.
Why people get stuck here
- Slides that are documents. Notes become bullets, bullets become paragraphs, and the audience reads instead of listening.
- Splitting at the wrong level. Splitting on every H2 gives four slides where you needed twelve, or the reverse.
- Code that’s unreadable from the back. Code blocks look fine in an editor and are illegible at presenting size.
- Notes and slides in different files. Speaker notes that live somewhere else get out of sync immediately.
What a good deck from Markdown looks like
One idea per slide
If a slide has two headings’ worth of content, it’s two slides. The cheapest presentation improvement available is splitting dense slides and saying the same words over more of them.
Around forty words maximum
Beyond roughly forty words, an audience switches from listening to reading, and they read faster than you speak. Anything longer belongs in speaker notes or a handout.
Speaker notes in the same file
Marking notes inline — a > block after the slide content, for instance — keeps them with the slide they belong to and out of the projected view.
| Split Rule | Gives You | Best For |
|---|---|---|
--- separators | Full control over breaks | Talks you’ve structured deliberately |
| Every H2 | One slide per section | Turning existing notes into a draft |
| Every H1 | Few, large slides | Short overview decks |
Common mistakes to avoid
- Pasting a whole paragraph and telling yourself you’ll trim it later.
- Using a code block longer than eight lines — nobody reads line nine on a projector.
- Forgetting to check the deck at presenting size, where type that looked fine becomes small.
- Writing notes as full sentences you then read aloud, which sounds exactly like reading aloud.
- Building the deck before the argument. If you can’t say the structure in three sentences, more slides won’t fix it.
How to do it with Markdown to Slides
The Markdown to Slides tool splits your text into slides and flags the ones that are too dense.
- Paste the Markdown you already have — meeting notes work fine as a starting point.
- Choose how slides split:
---separators for control, headings for speed. - Mark speaker notes so they stay with the slide but out of the projected view.
- Fix every slide flagged as too dense before presenting.
- Preview at full size, not in a small window.
Markdown’s original specification covers the syntax if you’re new to it. Other writing and planning tools are in the tools directory.
Frequently asked questions
How much text belongs on a slide?
Enough to anchor a point — a phrase, a number, an image. Around forty words is where an audience stops listening and starts reading. If your slide can be read aloud verbatim, it’s a document.
Do speaker notes show to the audience?
No. Notes are kept with the slide and rendered separately, for the presenter view only. That’s the entire reason to keep them in the same file.
Can I include images and code?
Standard Markdown images and fenced code blocks carry through. Code needs larger type than you expect, so check it at presenting size and cut it down to the lines that matter.
Final thought
The best thing about writing a deck in Markdown isn’t the speed — it’s that the structure is impossible to hide behind. If the outline reads badly as text, no amount of formatting will save the talk.