How to Turn Markdown into Slide Decks with Marp

Quick answer

Marp turns a Markdown file into a slide deck. You write normal Markdown — headings, lists, code fences, bold and italic all work exactly as they do anywhere else — and mark where one slide ends and the next begins with a horizontal ruler (---) on its own line. Run that file through Marp CLI or the Marp extension for VS Code, and it converts to HTML, PDF, or PowerPoint. Already know how to outline a long document in Markdown? You've got most of the skill you need here — a slide is just a section that ends at a ruler instead of a heading.

The rest of this guide covers writing the deck, converting it with Marp CLI, styling it with themes and front matter, and a few problems that trip people up the first time.

Step-by-step

Write the deck as Markdown

A Marp deck is one .md file. Each slide is a block of normal Markdown, and a --- on its own line — with a blank line above and below it — starts the next slide:

# Title Slide

A one-line subtitle goes here.

---

## Second Slide

- A bullet point
- Another bullet point

That's it for new syntax. Marp is built on CommonMark, so nothing else changes: code fences render with syntax highlighting, tables render as tables, and images resize with the same Markdown image syntax you already use.

Install and run Marp CLI

Marp CLI does the actual conversion. Install it as a dev dependency with npm install --save-dev @marp-team/marp-cli, or grab it via Homebrew on macOS and Linux with brew install marp-cli. To try it once without installing anything, run:

npx @marp-team/marp-cli@latest slide-deck.md

That converts to HTML by default. Add a flag to change the output format — marp --pdf slide-deck.md for PDF, marp --pptx slide-deck.md for PowerPoint, or marp --images png slide-deck.md to export every slide as a separate PNG. Marp CLI's own documentation covers two other modes worth knowing. Watch mode (marp -w slide-deck.md) re-converts and live-reloads the browser preview on every save. Server mode (marp -s ./slides) serves a whole directory of decks and returns a specific format by query string, like deck.md?pdf.

Set per-deck options with front matter

A YAML front-matter block at the top of the file controls deck-wide settings. theme: picks a theme, paginate: true turns on slide numbers, and header:/footer: set text that repeats on every slide:

---
theme: gaia
paginate: true
---

You can override any of these for a single slide with an HTML comment directive placed right after that slide's ruler — handy for turning pagination off on a title slide while the rest of the deck keeps it, per Marpit's documentation.

Style it

Three built-in themes ship with Marp — default, gaia, and uncover — or you can write a plain CSS file and register it as a custom theme. Got a diagram in the deck? It renders the same way it would in any other Markdown file; there's no special slide syntax for that either.

Common problems and fixes

PDF or PowerPoint export fails. Marp CLI renders PDF, PPTX, and image output through a headless browser, so it needs a local install of Chrome, Edge, or Firefox. HTML export doesn't have this requirement.

The deck looks unstyled, or a slide break didn't happen where expected. Check that the ruler sits on its own line with a blank line above and below it. A malformed ruler just gets treated as an ordinary horizontal rule inside one slide, not a break between two.

You need live component embeds or real-time collaborative editing, not just static export. That's outside what Marp is built for. A comparison of the three leading Markdown presentation tools found Marp's tradeoff is speed and portability, not interactivity — Slidev adds a Vue-powered interactive layer at real setup cost, and reveal.js trades simplicity for a bigger plugin and animation ecosystem. If your talk needs live-running code on a slide or a big animation set, one of those may fit better. If you just want a fast, portable deck straight from a Markdown file, Marp is the simpler tool for the job.

You want printable handouts, not just a screen deck. This is where Marp's PDF export is strongest of the three — it supports speaker notes and an outline view in the exported file, so it doubles as a leave-behind, not just a projector file.

The same "convert Markdown to another format" pattern shows up outside slides, too. Need a document (not a deck) turned into Word or PDF instead? Pandoc handles that conversion from the same kind of plain-text source.

Doing this with Carets

Draft the deck's Markdown in Carets before you ever run it through Marp CLI. It's plain text with one ruler convention added, so it fits the same editor you already use for notes and code — no format switch required to get from a rough outline to a deck.

Two things make this easier in Carets specifically. Markdown, plain text, and code all live in one editor, so writing the ruler-split deck feels the same as writing anything else, and any code fences in the deck get proper syntax highlighting while you're still drafting — before Marp ever touches the file. And because Carets organizes work into files, projects, and tags, the deck's .md file can sit right alongside the talk's notes and any code snippets it references, instead of living in a separate app.

Carets is native and fast, built for iOS and Mac rather than as a web wrapper. Open it on iPhone, iPad, or Mac and pick the deck back up wherever you left off. Get Carets on the App Store for iPhone, iPad, and Mac.

Frequently Asked Questions

Do I need to learn a new syntax to use Marp?

No. Marp is built on CommonMark, so any Markdown you already know renders the same way. The only addition is a horizontal rule (---) to mark where one slide ends and the next begins; everything else — headings, lists, code fences, images, bold and italic — works exactly as it does in a normal Markdown file.

Can Marp export to PowerPoint, not just HTML?

Yes. Marp CLI converts the same Markdown source to HTML, PDF, or PPTX with a flag (marp --pptx slide-deck.md), plus PNG images per slide. PDF, PPTX, and image export need a local Chrome, Edge, or Firefox install since Marp renders through a headless browser.

Do I need to install anything to try Marp?

No — run npx @marp-team/marp-cli@latest slide-deck.md to convert a file once without installing. For repeated use, install it as a dev dependency with npm, or via Homebrew on macOS.

How do I change the look of a Marp deck?

Pick one of the three built-in themes (default, gaia, uncover) with a theme: line in the file's YAML front matter, or write a plain CSS file and register it as a custom theme. Front matter also controls per-deck options like paginate, header, and footer, and those same settings can be overridden for a single slide.

Conclusion

Marp turns the Markdown you already know into a slide deck with one added convention — the ruler — and a one-line CLI command to convert it. Once the deck lives as a plain-text file, it's versionable, diffable, and portable the same way any other Markdown document is. That makes it easy to keep next to the rest of your writing instead of off in a separate presentation app.