How to Compress Documentation and Code Screenshots Without Blurry Text
What matters most in a documentation screenshot is small text: a semicolon in code, a menu name, a one-line hint on a button. Blur those and readers cannot follow along.
Make the screenshot readable first
Before capturing, increase the editor font size, hide unrelated panels, and use a clear theme. Compression cannot sharpen strokes that are only a few pixels wide to begin with.
- Keep only the area readers need for the step.
- Use callouts to point at the action instead of showing the whole UI.
- Never capture account secrets or keys.
Crop and display size come first
A full 4K desktop squeezed into a 700px-wide article makes small text unreadable. Crop to the step, or split a complex screen into several images — smaller files and faster understanding.
High-DPI screenshots have 2× or 3× the display pixels. If the docs page does not need retina sharpness, "Scale to 1/2" cuts the pixel count to a quarter; if most readers use high-DPI screens, keep the original size and compress only the format.
What each approach does to a screenshot
| Approach | Setting | Quality | Size | Best for |
|---|---|---|---|---|
| Lossless PNG optimisation | High quality (oxipng level 2, no quantization) | Pixels unchanged | Usually a small saving | Screenshots with gradients, shadows, or photos |
| PNG palette quantization | Balanced (quality 80) or Smart auto | Fewer colours, barely visible on flat UI | Usually a large saving | Flat UI, code, terminal screenshots |
| JPEG | Convert all to JPEG + High quality (90) | Possible noise around text | Smallest for photo content | Screenshots dominated by photos |
Without resizing or a forced format, if a PNG cannot be made smaller than the original, the tool hands back the original rather than a larger file. PNGs from screenshot tools are sometimes already tightly packed — that is normal.
Checklist
- View at the final page's display scale, not just zoomed in an image viewer.
- Read code punctuation, underscores, and indentation character by character.
- Check transparent edges on both light and dark themes.
- Avoid repeated copy-paste and JPEG re-saves; each save loses a little more.
Updates and accessibility
When the product UI changes, old screenshots mislead. Name files by feature and step rather than temporary numbers, and after a UI update just drag the new screenshot folder in and process it again.
References
Your files are processed in the current browser and are not uploaded as article samples.