Marp tutorial for teaching: Markdown slides for lectures

By Ekrem Çetinkaya · Published 8 September 2026 · Türkçesi

Marp turns a Markdown file into a slide deck: a front matter block switches it on, a line with three dashes starts a new slide, and HTML comments hold presenter notes. For teaching this means a lecture is one plain-text file per week that you can version, diff, search and regenerate, and export to PDF or PPTX when you need them.

This tutorial covers the syntax an instructor actually uses, in the order you meet it. It assumes nothing beyond basic Markdown.

What is Marp?

Marp is the "Markdown Presentation Ecosystem": a core library (Marpit) that renders Markdown to HTML slides with CSS themes, a VS Code extension that previews and exports, and a command-line tool, marp-cli, that converts files to HTML, PDF and PPTX. It is open source (MIT). Slides are plain Markdown with a few conventions on top, so the same file opens in any editor.

A minimal deck

---
marp: true
theme: default
paginate: true
---

# Week 3: Processes

## What you will be able to say by the end

---

# A process is in exactly one of five states

- new, ready, running, waiting, terminated
- a process moves between them; it never sits in two

<!-- Silberschatz 3.1. Draw the state diagram before advancing. -->

Three things happen here:

marp: true in the front matter tells Marp (and the VS Code extension) to treat the file as a deck.
--- on its own line separates slides. The first --- pair is the front matter, every later one is a slide break.
The HTML comment is a presenter note. It is invisible on the slide and shows in presenter view. Several comments on one slide are joined.

Front matter you will use

Key	What it does
`theme`	`default`, `gaia` or `uncover` (built in), or the name of your own theme
`paginate: true`	slide numbers
`size: 16:9`	aspect ratio; `4:3` also works
`header` / `footer`	text repeated on every slide, for a course code or a source line
`style`	a block of CSS applied to the whole deck

Example with a footer that carries the course code:

---
marp: true
theme: gaia
paginate: true
footer: "BLM2012 · Operating Systems · Week 3"
---

Directives: changing one slide

A directive is an HTML comment with a key and a value. With an underscore it applies to the current slide only; without it, to this slide and every slide after.

<!-- _class: lead -->
# Section 2: Scheduling

---

<!-- _backgroundColor: #f5f5f5 -->
<!-- _color: #151515 -->
# A slide with its own colours

_class: lead is the one you will use most: in the built-in themes it centres the slide, which is what a section divider wants. _paginate: false hides the page number on a title slide. _header and _footer override the deck-wide ones.

Images and backgrounds

Plain Markdown images work, with size hints in the alt text:

![width:600px](figures/state-diagram.svg)
![h:320px](figures/queue.png)

Background images use the bg keyword, and can be split so text sits beside them:

![bg right:40%](figures/cpu.jpg)
# The image takes the right 40%, the text the rest

---

![bg contain](figures/full-diagram.svg)

contain fits the whole figure, cover fills the slide. For teaching, bg right with a redrawn diagram is the layout that reads best from the back of a room.

Themes: gaia, uncover, and your own

default is neutral and dense: the most text per slide, good for code.
gaia has a stronger title style and a coloured lead slide; the classic lecture look.
uncover is centred and sparse; suits talks more than lectures.

To make the deck look like your course, write a CSS file that imports a built-in theme and overrides a few rules:

/* @theme lecture */
@import "gaia";

section { font-family: "IBM Plex Sans", system-ui, sans-serif; font-size: 28px; }
section.lead h1 { font-size: 64px; }
footer { font-size: 16px; color: #737373; }

The /* @theme lecture */ comment names the theme; you then write theme: lecture in the front matter and pass the CSS file to the tool (--theme lecture.css in marp-cli, or the markdown.marp.themes setting in VS Code). Lecture Studio ships two such themes, one for lectures and one for talks, and applies them in its preview.

Code, math and tables

Fenced code blocks are highlighted by language. Math uses $...$ and $$...$$; Marp Core renders it with MathJax by default, or KaTeX if you set math: katex in the front matter. Tables are GitHub-style. All three fit on a slide only if they are short; a 30-line listing belongs in the handout with the interesting five lines on the slide.

Presenter notes

Anything in an HTML comment that is not a directive is a note:

# Context switches are pure overhead

- registers, program counter, memory maps saved and restored
- nothing useful runs during the switch

<!--
Ask: what is the cost if it happens 1000 times a second?
Source: os-book 3.2.3. Timing on the lab machines is in lab-03.
-->

Notes show in the presenter view of the VS Code extension and of Lecture Studio, and can be exported as text with marp --notes. There is a separate guide on writing speaker notes in Marp.

Exporting

For the classroom projector, PDF is the safest format; for colleagues who want to edit, PPTX. Both come from marp-cli:

marp week3-slides.md --pdf
marp week3-slides.md --pptx

The details, including the editable PPTX option and what it loses, are in exporting Marp to PDF and PPTX.

A template for a course

A file structure that has held up over several terms:

course/
  syllabus.md
  sources/               readings shared by every week
  week3/
    week3-slides.md
    week3-instructor-guide.md
    assets/              figures referenced by the deck
    sources/             readings for this week only

Each deck starts with the same front matter, a lead slide with the week's question, a slide listing what students will be able to say, the body, a summary slide that repeats the claims, and a closing slide with contact lines. Lecture Studio creates this structure for a new course or a new talk, and writes the deck into it from the sources in those folders. It runs on macOS and needs an Oberik project key for the assistant.

FAQ

Is Marp free?

Yes. Marp, Marpit, the VS Code extension and marp-cli are open source under the MIT licence.

Can I present a Marp deck without exporting it?

Yes. The VS Code extension has a presenter view; marp-cli's --preview flag opens a window; the HTML output opens in any browser. Lecture Studio has a presenter mode with an audience screen.

Does Marp support speaker notes?

Yes. Notes are HTML comments inside a slide. They appear in presenter views and can be exported with marp --notes.

Can I convert an existing PowerPoint to Marp?

Not automatically with Marp's own tools. The usual route is to rewrite the deck from the readings, which is faster than it sounds and produces a cleaner deck; see how to make lecture slides from your readings.