Speaker notes in Marp: how to write and present them
In Marp, speaker notes are HTML comments inside a slide: anything between <!-- and --> that is not a directive is a note. They stay invisible on the slide, show in presenter view, and export as text or as PDF annotations. Good notes are short, say what is not on the slide, and name the source and the one thing to remember.
This guide covers the mechanics first, then how to write notes that are useful when you are standing in front of a room.
What are speaker notes?
Speaker notes (presenter notes) are the text a presenter sees that the audience does not. In PowerPoint and Google Slides they live in a pane under the slide; in Marp they live in the Markdown itself, next to the slide they belong to. Because they are part of the file, they are versioned with the deck and never get separated from it.
Where do notes go in a Marp deck?
Inside the slide, after the content, as an HTML comment:
---
# Context switches are pure overhead
- registers, program counter, memory map saved and restored
- nothing useful runs during the switch
<!--
Ask the room: how many switches a second on the lab machines?
Source: os-book 3.2.3; timing table in lab-03.
Do not skip the diagram; the next slide assumes it.
-->
Rules the renderer applies:
- A comment that starts with a directive (
<!-- _class: lead -->) is not a note. Everything else is. - Several comments on one slide are joined into one note, in order.
- A comment before the first
---after the front matter belongs to the first slide. - Markdown inside the comment is not rendered; write plain lines.
How do I see the notes while presenting?
- VS Code with the Marp extension: open the preview, choose presenter view; the current slide, the next slide and the notes are on your screen, the slide alone on the projector.
- marp-cli HTML output: open the HTML in a browser and press
Pfor presenter view (the bespoke Marp HTML template supports it). - Lecture Studio: presenter mode puts the slide on the audience screen and keeps the notes, the next slide and a break countdown on yours. The note strip under the preview also shows the current slide's note while editing.
How do I export the notes?
marp deck.md --notes # deck.txt, one block per slide
marp deck.md --pdf --pdf-notes # notes as annotations in the PDF
marp deck.md --pptx # notes carried into PowerPoint's notes pane
The editable PPTX mode (--pptx-editable) does not carry notes; the default PPTX does.
How long should speaker notes be?
Short enough to read in a glance between two sentences. A working ceiling is five lines per slide; a good note is often two. Notes are not a script. If you find yourself writing paragraphs, either the slide is missing a claim that should be on it, or the paragraph belongs in the instructor guide, not in the deck.
A test: if the projector dies and you present from the notes alone, can you? If yes, the notes are complete. If they are also longer than the slides, they are too long.
A pattern for notes that help in the room
For each slide, at most one line of each:
- The claim in your own words, in case the slide title is not how you would say it aloud.
- What is not on the slide: the example, the number, the caveat you will say.
- The source and location, so a question can be answered with a page number.
- A prompt for the room: a question to ask, a show of hands, a pause.
- A warning to yourself: "do not skip", "time check: minute 40", "skip if late".
Written that way, the notes for a twenty-slide lecture fit on two printed pages and stay readable at arm's length.
Notes for the whole session, not just the slides
Some things belong to the session rather than to a slide: timing per section, where students got lost last term, what to cut when running late. Keep those in a short instructor guide next to the deck instead of stuffing them into the first slide's note. The guide and the notes then divide the work: the guide plans the hour, the notes carry the slide-level detail.
Writing notes with an assistant
If an assistant writes the notes, give it the deck and the sources, and ask for notes slide by slide that name the source for each claim and never restate the slide text. Check the sources it cites; that is the whole point. Lecture Studio does this from the chat panel: the note for each slide is written into the deck as a comment, with the readings it came from, and the slide content is left untouched. The app runs on macOS and needs an Oberik project key.
FAQ
Are Marp speaker notes visible to the audience?
No. Notes are HTML comments, so they never render on the slide. They appear only in presenter views and in exports that include notes.
Can a slide have more than one note?
Yes. Several comments in one slide are concatenated into a single note in the order they appear.
Do notes survive export to PowerPoint?
In the default PPTX export, yes, as PowerPoint notes. In the editable PPTX export (--pptx-editable), no.
How long should speaker notes be?
Two to five short lines per slide. They should let you present without the projector, but they should not be longer than the slides themselves.