Compress Screenshots for Documentation Without Blurry Text

The hard limits are the ones where you attach files directly, such as GitHub. Docs sites mostly have soft limits: slow pages, large repositories and readers on bad connections. These are the published figures, each read on the date shown at its source.

MDN’s advice to prefer lossless for screenshots is the reason to be careful here. Smol has no lossless mode for images; it always re-encodes. That is fine for a docs page read in a browser, as long as you zoom in on the result (the settings section shows how). If you need pixel-identical output, a lossless optimizer such as ImageOptim is the right tool, and we say so on our own comparison page.

Check your own platform’s help page for its ceiling before you set one. If your docs live in a wiki, our guide to Notion and Confluence uploads covers that case.

Resize first, then set quality. The pixel count drives file size more than the quality slider does, and a docs column rarely shows more than 800 to 1000 CSS pixels of width.

Smol sets quality and pixel size, not output bytes, so check the largest file in the folder against your cap. It does have a target-file-size mode for images that accepts 4 to 4096 KB; it aims for a band, can land over your number, and is slow, about 28 seconds for one 768 × 512 image. Use it only for the odd file that refuses to fit.

How do I check that the text is still readable?

• Open the output at 100% and read the smallest label in the image, not the title bar.
• Compare a menu with thin gray text before and after. Banding around letters means raise quality.
• Judge it at the size readers see, which on a Retina display means looking at it at 2x.

For a sense of what quality does to a lot of PNGs at once, our benchmark compressed 24 small (768 × 512) photographs as PNG at quality 75 and saved 69.2%. ImageOptim at its default lossless settings saved 4.3% on the same files. Photographs are not UI screenshots, so treat those figures as direction, not a promise for your screens.

A Retina screenshot is large because macOS captures every physical pixel. The 14-inch MacBook Pro in our screen recording test produced 3024 × 1964 frames, 5.94 megapixels, or 2.86 times a 1080p frame.

You do not need all of it. MDN’s responsive images guide describes serving a higher-resolution file to denser screens at the same display size, and its example is 39 KB for a 320 px image and 93 KB for the 640 px version. So the right docs image size is a pixel width of about twice the column, and the file size follows from that. Past 2x, extra pixels add bytes without adding sharpness.

A practical rule for a docs team: pick one column width, write down 2x of it, and give every contributor the same number. Smol’s resize modes are fit, fill, width and height. Use fit so nothing is cropped (fill crops, with no control over what goes). One job produces one size, so if your docs serve 1x and 2x files, that is two runs.

Use MP4 for almost any clip longer than a second or two. In web.dev’s example the GIF was 3.7 MB, the MP4 551 KB and the WebM 341 KB, and each GIF pixel is only an 8-bit index into a palette.

In our own GIF to MP4 measurements, a 5-second UI clip at 1280 × 800 was 183,238 bytes as a GIF and 72,948 as H.264 at CRF 23, which is 2.5 times smaller. A photographic clip was 33.5 times smaller. Interface recordings are the near-best case for GIF, and the video still won.

To make video behave like a GIF on a page, web.dev recommends <video autoplay loop muted playsinline>. One caution from our tests: Smol does not convert animated GIFs. Record or export as video instead, and let Smol compress that. The GIF to MP4 guide shows the route that works.

Work in batches, per release or per article. macOS drops screenshots on the desktop by default and records to .mov, so the pile builds up quickly.

1. 1

   Collect the originals in one folder

   Keep them untouched. Smol writes a copy with a _compressed suffix beside each file by default.

2. 2

   Drag the folder into Smol

   Screenshots and recordings can go in the same batch. Each file shows its own progress and savings.

3. 3

   Set images to PNG at quality 75 and a maximum dimension of 2x your column

   Leave the resize mode on fit. Then raise quality for any image with dense small text.

4. 4

   Set video to MP4, resolution 1920, quality High

   On a 60-second, 56,384,195-byte Retina recording, Smol’s default (H.265, High) gave 3,691,160 bytes, 93.5% smaller, and resolution 1920 gave 1,399,221 bytes at 1662 × 1080, 97.5% smaller. That was Smol 1.0.34, and the recording had no audio. For widest playback choose H.264 and check that the clip plays where your docs are viewed.

5. 5

   Check the biggest file and one image at full zoom

   Sort by size, confirm the cap you care about, and read the smallest text in one screenshot before you upload the batch.

If your screenshots collect in one folder, you can have Smol watch it. Our watched folder guide explains the catch: watched folders can make already-optimized files larger, so use them only for fresh, unoptimized screenshots. The Finder Quick Action is the alternative when you would rather compress on demand. For repositories, compress before you commit; see why Git never forgets. Trim dead time from a recording before you compress it. Support teams recording customers’ screens will find more in our screen recordings for support guide, and README-heavy repositories in the GitHub README media guide. Read the screen recording guide for what moves the size.

Free options come first here, because for a handful of images they are often enough.

Teams pricing: Smol is Solo $29 once for one Mac, Team $49 once for three Macs, or Enterprise at $20 a seat for 5 to 500 seats. Presets live on one Mac, so a docs team keeps consistent output by writing the settings down (format, quality, maximum dimension) in the style guide and recreating the preset on each Mac. If your build system needs compression on a server, the Smol API exists for that.

It is the wrong tool in a few clear cases, and a short list saves you a purchase you do not need:

• You need lossless or pixel-identical screenshots, for example to show a one-pixel misalignment. Smol always re-encodes; use a lossless optimizer.
• Your diagrams are SVG. Smol does not handle SVG.
• You must convert animated GIFs. Smol cannot convert them (tested in 1.0.34), so re-export from your recorder as video.
• Your pipeline is a Linux CI build. Use an image library in the build, or the Smol API.
• You have a handful of images a year. Preview and the free tools above are enough.