Marp images: sizes, backgrounds, splits and filters
Marp extends the Markdown image with keywords in the alt text:  sizes it,  makes it the slide background,  splits the slide with the image on the right, two ![bg] images sit side by side, and  or  applies a CSS filter. Everything else is the Markdown you already know; the Marp tutorial for teaching covers that side.
This guide lists the syntax with an example of each, then the layout patterns a lecture deck uses (figure with caption, image beside text, full-bleed section slide), and the two places images fail on export.
Sizing an inline image
w and h are shorthand for width and height; a number without a unit means pixels, so w:400 and width:400px are equivalent. Set one dimension to preserve the image's aspect ratio. Setting both width and height can stretch it.
Inline images accept auto and CSS lengths such as px, em and cm, but not percentages or viewport-relative units such as vw, vh, vmin and vmax. width:50% does not resize an inline image. Use a length such as width:400px instead; see the official Marpit image-sizing documentation.
Percentages work in background syntax, but describe different things:  controls the background image's scale, while  reserves 40% of the slide width for the background area. Neither is an inline image width.
An image without an explicit size uses its intrinsic dimensions, subject to the theme's CSS limits. Set widths in the deck rather than downsampling the source file, so the original image remains available for export.
Background images
A background image fills the slide behind the content. Sizing keywords change how:
| Keyword | Effect |
|---|---|
![bg cover] |
fill the slide, crop what does not fit (default) |
![bg contain] or ![bg fit] |
fit inside the slide, letterboxed |
![bg auto] |
natural size |
![bg 60%] |
scaled to 60% of the slide |
Text on a photo is hard to read; combine with <!-- _color: white --> or a dark overlay from the theme, or use the split below instead.
Split layouts: image beside text
# The scheduler's view
- ready queue
- running process
- quantum
bg left and bg right push the content to the other side; the percentage is the image's share of the width. This is the most useful image layout for teaching: the diagram stays large and the bullets stay readable. It needs Marp's inline SVG mode, which Marp CLI and the VS Code extension have on by default.
Several backgrounds on one slide
Two bg images share the slide side by side; add ![bg vertical] to the first to stack them instead. Combine with sizing (![bg contain]) so each is letterboxed rather than cropped. Three or four work too, for a comparison slide.
Filters
Available: blur, brightness, contrast, drop-shadow, grayscale, hue-rotate, invert, opacity, saturate, sepia. A blurred, darkened background under a title is the standard fix for text on a photo.
Patterns a lecture deck uses
- Figure with caption: the image sized with
w:, a line in<small>or a.captionclass under it naming the source and page. The caption is what makes the figure citable. - Diagram beside bullets:
![bg right:45%]with three to five bullets on the left. - Section slide:
![bg brightness:0.5]full-bleed photo with a one-line title in white. - Before and after: two
![bg contain]images. - Centred image: Marp has no
centerkeyword; the theme can add one withimg[alt~="center"] { display: block; margin: 0 auto; }, then.
Keep the images in an assets/ folder next to the deck and reference them with relative paths; the deck then moves with its images.
What breaks on export
- Missing images in PDF or PPTX from marp-cli: local files are blocked by default when rendering (marp-cli prints a warning naming the option); add
--allow-local-filesfor a deck you wrote yourself. Tested with marp-cli 4.5.1: without the flag the PDF has no images, with it both render. - Image too large for the slide:
bg containor aw:size; the PDF is the same 1280×720 canvas as the preview, so what overflows there overflows in print. - Editable PPTX:
--pptx-editableapproximates layouts with shapes; backgrounds and filters may not survive. The default PPTX renders each slide as an image and keeps them.
In Lecture Studio
Lecture Studio's editor has an Image button that inserts , the split layout above, pointing at the unit's assets/ folder where the deck's images live; the preview renders every keyword on this page. The Check slides scan in the preview flags two things: slides whose content runs past the edge, which is where an unsized screenshot shows up, and images that fail to load, which is a wrong path caught before the lecture. Export is marp-cli's job, with the flag above; see exporting Marp to PDF and PPTX. The app runs on macOS 15 or later and needs an Oberik project key for the assistant; the editor and preview work without one.
FAQ
How do I resize an image in Marp?
Put a length in the alt text: ,  or . Unitless numbers mean pixels. Set only width or height to preserve the aspect ratio. Inline percentage widths such as width:50% are not supported; percentages are supported for background sizing () and split widths ().
How do I put an image on the right and text on the left in Marp?
 at the top of the slide; the content flows on the left. bg left does the opposite.
How do I set a background image for one slide?
 on that slide. Add contain, cover, auto or a percentage to control sizing, and filters such as blur:4px or brightness:0.6.
Why are my images missing in the PDF?
marp-cli blocks local files by default when converting; run it with --allow-local-files, and check the paths are relative to the Markdown file.