lecture.studio

Marp images: sizes, backgrounds, splits and filters

By Ekrem Çetinkaya · Published

Marp extends the Markdown image with keywords in the alt text: ![w:400](fig.png) sizes it, ![bg](photo.jpg) makes it the slide background, ![bg right:40%](photo.jpg) splits the slide with the image on the right, two ![bg] images sit side by side, and ![blur:4px](…) or ![grayscale](…) 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:400](assets/fig-3.png)
![h:300](assets/fig-3.png)
![w:400 h:300](assets/fig-3.png)
![width:50%](assets/fig-3.png)

w and h are shorthand for width and height; the value takes any CSS length. An image without a size renders at its natural size, which for a screenshot is usually too large. Set widths in the deck rather than resizing the file, so the source image stays sharp for PDF.

Background images

![bg](assets/campus.jpg)

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

![bg right:40%](assets/diagram.png)

# 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

![bg](assets/before.png)
![bg](assets/after.png)

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

![bg blur:6px brightness:0.6](assets/campus.jpg)
![grayscale w:300](assets/old-figure.png)
![opacity:0.5](assets/overlay.png)

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

  1. Figure with caption: the image sized with w:, a line in <small> or a .caption class under it naming the source and page. The caption is what makes the figure citable.
  2. Diagram beside bullets: ![bg right:45%] with three to five bullets on the left.
  3. Section slide: ![bg brightness:0.5] full-bleed photo with a one-line title in white.
  4. Before and after: two ![bg contain] images.
  5. Centred image: Marp has no center keyword; the theme can add one with img[alt~="center"] { display: block; margin: 0 auto; }, then ![center w:500](…).

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

In Lecture Studio

Lecture Studio's editor has an Image button that inserts ![bg right contain](./assets/….png), 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 the size in the alt text: ![w:400](img.png), ![h:300](img.png) or ![width:50%](img.png).

How do I put an image on the right and text on the left in Marp?

![bg right:40%](img.png) 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?

![bg](img.jpg) 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.

More guides