Marp auto-scaling: fit headings, code that shrinks, overflow

By Ekrem Çetinkaya · Published 15 September 2026

Marp scales two things automatically: a heading marked # <!--fit--> grows or shrinks to the slide width, and a code block shrinks when it is too wide (never grows). Both are switched on by a line in the theme, /* @auto-scaling true */; a custom theme without that line gets neither. Everything else — paragraphs, lists, tables — overflows silently and is simply cut off at the slide edge.

This guide covers the fit comment, code and math scaling, the theme flag that enables them, and the fixes for a slide that runs past the bottom.

A heading that fills the slide

# <!--fit--> Operating Systems, Week 5

The comment goes inside the heading line, after the #. Written on its own line it is read as a Marpit directive comment and does nothing — the most common reason "fit doesn't work".

Rendered, that heading becomes <h1 is="marp-h1" data-auto-scaling>: a custom element that measures the text and scales it both up and down. A short title grows to fill the width, a long one shrinks. It is the right tool for a title slide or a section divider where the text length changes every week.

Code blocks shrink, but never grow

A fenced code block renders as <pre is="marp-pre" data-auto-scaling="downscale-only">. Long lines are shrunk until they fit; short snippets stay at the theme's code size. Nothing is reflowed, so a 200-character line becomes small rather than wrapped — past a point, split the line instead.

Downscaling has no floor. A whole file pasted onto one slide will technically fit and be unreadable in the back row. The font size guide has the sizes that survive a lecture hall; the practical limit is around 15 lines of code per slide.

Math

With the default math engine (MathJax) the equation is an SVG that already scales itself to the width. With math: katex in the front matter, KaTeX output is wrapped in the same auto-scaling element as headings. Either way a long equation shrinks rather than overflows; see math in Marp for the engine difference.

The theme flag

The built-in themes — default, gaia, uncover — all declare auto-scaling. A custom theme must opt in:

/* @theme cs101 */
/* @auto-scaling true */

@import 'default';

The flag takes values, tested on Marp Core 4.4:

If <!--fit--> stopped working the day you switched to your own theme, this line is why.

Scaling needs the browser script

The scaling happens in the browser: Marp ships a small script that defines the custom elements and re-measures on resize. marp-cli includes it in HTML, PDF, PPTX and image exports, so the output is correct everywhere. It matters only if you render with Marp Core yourself and drop the script — then a fit heading renders at its normal size.

When the slide overflows anyway

Prose, lists and tables are not scaled. A slide with too much on it is cut off at the edge, in the preview and in the PDF alike. In order of preference:

1. Split the slide. Two slides cost nothing; --- is cheaper than shrinking.
2. Cut the text. Most overflow is a paragraph that belongs in the speaker notes.
3. Set a size for one slide with a scoped style: <style scoped>section { font-size: 24px; }</style>.
4. Shrink a table with section table { font-size: 18px; } rather than dropping rows.

In VS Code, the setting markdown.marp.diagnostics.slideContentOverflow (off by default) flags a slide whose content runs past the safe area — worth turning on for a lecture deck. A quick check before class: export the PDF and look at the last line of every slide. Overflow is invisible in a fast scroll of the editor and obvious in the PDF.

In Lecture Studio

Lecture Studio writes Marp Markdown, so the same rules apply to the decks it produces; the app is free during the beta and needs an Oberik project key. The online editor renders any of the snippets above in the browser if you want to see the scaling before changing your deck.

FAQ

How do I make text fit the slide in Marp?

Put <!--fit--> inside the heading line: # <!--fit--> Title. It works on headings only, and only when the theme declares /* @auto-scaling true */.

Why is my Marp fit heading not scaling?

Two usual causes: the comment is on its own line instead of inside the heading, or the custom theme is missing the @auto-scaling line.

Does Marp shrink long code blocks?

Yes, downscale only. A wide code block shrinks to fit; a narrow one is not enlarged. Lines are never wrapped.

What happens when a Marp slide overflows?

The content is cut off at the slide edge with no warning. Split the slide, cut the text, or set a smaller font size for that slide.