Fit an image to a Marp slide: bg contain, sizes, fit text
To fit an image to a Marp slide, use : the image scales to fit inside the slide without cropping, letterboxed if the ratios differ. ![bg cover] fills the slide and crops;  sizes an inline image by width and ![h:600] by height. For a heading that is too long, # <!-- fit --> Title scales it to one line. All tested on Marp Core 4.
This guide gives the cases (a figure, a screenshot, a full-bleed photo, image beside text, a heading), then the rule for which to use.
A figure that should be as large as possible
The whole image, as large as the slide allows, centred, with empty bands on two sides if the ratios differ. Nothing else fits on the slide except a header and footer; put the caption in the footer for that slide (<!-- _footer: "Figure 3: Tanenbaum & Bos, 2015" -->).
If the image should leave room for a title:
# The convoy effect
h:520 on a 720-tall slide leaves the title's space and keeps the image whole; the width follows the ratio. Adjust the number once per theme (base font and padding decide how much room a title takes).
A screenshot that is too tall
Screenshots are portrait or square; slides are wide. Options, in order:
- Crop the screenshot to the part that matters before it goes in the deck.
- Beside text:
gives the image the right 45% at full height and the text the left. and accept the narrow image.
Do not ![w:1200] a tall image: it overflows the bottom, and Marp does not shrink content to fit.
A full-bleed photo
Fills the slide and crops the excess (the default for bg, so cover can be omitted). If the crop cuts the wrong part, crop the photo to its focal point before it goes in the deck. For a title over it, add brightness:0.5.
Image beside text
The image takes 40% of the width at full height (cropped to fit unless contain is added), text flows on the left. The most useful layout in a lecture deck; details in Marp images.
Fit a heading
# <!-- fit --> A heading that would otherwise wrap onto three lines
Marp Core scales the heading to fit one line of the slide width. Use it for section titles; body text has no fit keyword and should not need one.
Fit content: what Marp does not do
Marp does not auto-shrink a slide's content to fit the canvas (code blocks are the exception: they scale down to the width). An overflowing slide is cut off in the PDF. The remedy is editorial, not a flag: split the slide, cut a bullet, or size the image. The Check slides scan in Lecture Studio lists the slides that overflow.
The rule
| Want | Write |
|---|---|
| Whole image, as big as possible, alone |  |
| Whole image under a title |  |
| Fill the slide, cropping is fine |  (cover) |
| Image beside bullets |  (contain to avoid cropping) |
| Tall screenshot | crop, or bg right contain |
| Long heading | # <!-- fit --> … |
FAQ
How do I fit an image to a slide in Marp?
 for the whole image as large as possible without cropping;  to leave room for a title.
What is the difference between bg contain and bg cover?
contain fits the whole image inside the slide (letterboxed); cover fills the slide and crops. cover is the default for bg.
How do I fit text to a Marp slide?
Headings: # <!-- fit --> text scales to one line. Body text has no fit option; shorten it or split the slide.
Why is my image cut off in the Marp PDF?
It is larger than the slide and Marp does not shrink content. Use bg contain, an h: size, or crop the image.