Marp not working: theme, images, preview and export fixes
Most Marp problems are one of five: the theme name does not match a registered theme, so the deck renders with the default styling; local images are dropped from a PDF unless --allow-local-files is passed; inline style and id attributes are stripped by the sanitiser; the preview is looking at a file you are not editing; or export cannot find a browser. Each has a one-line fix once you recognise it.
This guide lists the failures with the exact symptom, why it happens, and the fix, all checked on marp-cli 4.5.1 with Marp Core 4.4.
The deck ignores my theme
Symptom. The slides render, but with the default look; your colours and fonts are nowhere.
An unknown theme name fails silently. theme: cs101 when no theme called cs101 is registered produces the same CSS as the default theme and no warning at all — nothing on the console, no error code.
marp deck.md --theme-set themes/ -o deck.html # register a folder
marp deck.md --theme themes/cs101.css # or a single file
Two things to check: the /* @theme cs101 */ comment at the top of the CSS file must match the theme: value exactly (it is the theme's real name, the filename is irrelevant), and on the command line the theme flags must come after the input file. In VS Code, the folder goes in the markdown.marp.themes setting instead.
Images are missing from the PDF
Symptom. Images show in the preview and the HTML, and are blank in the PDF, PPTX or PNG.
Export renders in a headless browser that refuses local files by default:
marp deck.md --pdf --allow-local-files
The flag is a real security decision, not a formality — it lets the rendered page read files from the machine — so use it on decks you wrote. Remote images over https: need no flag. Background images follow the same rule; see images and backgrounds.
My HTML disappeared
Symptom. A <div> survives but its style attribute is gone; an <iframe> or an inline <svg> never appears.
Marp sanitises HTML. Since Marp Core 4, a div or span carrying a class renders without any flag, which is why two-column layouts work out of the box. What is removed: inline style and id attributes, <iframe>, and inline <svg>. <video> and <audio> are allowed. Put the styling in the theme or a <style scoped> block instead of an inline attribute, and see video, iframes and SVG for what to embed instead.
In VS Code, the markdown.marp.html setting (off, default, all) decides how much HTML the preview accepts; all in the preview and a stricter setting in the CLI is a common source of "it worked in the preview".
The preview is stale
Symptom. Edits do not show, or the preview shows yesterday's slide.
- In VS Code, the preview follows the active Markdown file. A preview pinned to another tab will not update; close it and reopen from the file you are editing.
- The front matter must start on line 1, with
marp: truein it. A blank line above---turns the block into a horizontal rule and the file is rendered as an ordinary document. - With the CLI, use
-wto watch or-sto serve a folder; a plain run converts once and exits. See watch and server mode.
Export fails or hangs
A run that never finishes. marp-cli reads Markdown from stdin when it is available. Started from a script or an editor task with an open pipe, it waits for input that never comes. Close it: marp deck.md --pdf < /dev/null.
No browser found. PDF, PPTX and image export drive Chrome, Edge or Firefox. Point at one explicitly when the automatic search fails:
marp deck.md --pdf --browser-path /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
CHROME_PATH=/usr/bin/chromium marp deck.md --pdf
In a container or on a CI runner, CHROME_NO_SANDBOX=1 is usually the missing piece, and --browser-timeout 60 helps on a slow machine with a large deck.
A command that broke after a system update. A globally installed marp-cli is bound to the Node it was installed with. After a Node major upgrade, an old install can fail with ReferenceError: require is not defined in ES module scope from its bundled argument parser. Reinstall it, or run npx @marp-team/marp-cli@latest; the install guide covers both.
Smaller ones
- Fit heading does nothing.
<!--fit-->belongs inside the heading line, and the theme must declare/* @auto-scaling true */. See auto-scaling. - Text runs off the slide. Only headings, code and math scale. Everything else is cut off; split the slide.
- Emoji are blank in an offline PDF. Emoji are fetched as images from a CDN by default; see emoji in Marp.
- Page numbers are wrong after a skipped slide.
_paginate: skipremoves the slide from the count;holdkeeps the number. See header, footer and page numbers. - Math does not render.
math: mathjaxis the default since Marp Core 3;math: falsedisables it, and a stray$in prose can start an expression.
FAQ
Why does Marp ignore my custom theme?
Because an unrecognised theme name falls back to the default silently. Check that /* @theme name */ matches the theme: value and that the CSS is registered with --theme-set (after the input file) or the VS Code themes setting.
Why are images blank in my Marp PDF?
Local files are blocked during export. Add --allow-local-files, or host the images over https.
Why is my Marp preview not updating?
The preview is following another file, or the front matter does not start on line 1. With the CLI, use -w or -s — a plain run converts once.
Why does marp-cli hang with no output?
It is waiting on stdin. Add < /dev/null when running it from a script or an editor task.