PNG to WebP for GitHub READMEs: Smaller Screenshots, Faster Docs
A great README with screenshots loads fast — a great README with uncompressed screenshots loads like a slideshow. PNG screenshots are the usual suspect: a single 4K editor screenshot can be several megabytes, and a README with five of them turns your project's front page into a bandwidth test. GitHub renders WebP in READMEs just fine, so converting those screenshots is one of the cheapest documentation upgrades you can make.
Why screenshots bloat so fast
Screenshots of code, terminals, and UIs are mostly flat colors and sharp edges — exactly the content PNG compresses worst. Screenshots with photographic content (browser demos, video frames) compress even worse. Either way, the README that "just has a few images" quietly ships megabytes of PNG to every visitor, including every CI badge crawler and search engine bot.
WebP's lossy mode typically cuts screenshot sizes dramatically while keeping text readable, and its lossless mode still beats PNG for UI-style content. Either way your docs get faster.
The workflow I use before every release
1. Capture at a sane resolution. A 4K screenshot scaled down to 1600px wide is indistinguishable in a README and a fraction of the size. Most screenshot tools let you set the capture area — use it.
2. Convert to WebP before committing. Don't let PNG screenshots pile up in the repo. When I need to shrink PNG screenshots to WebP in your browser, I use a tool that converts locally — the file never uploads, which matters when your screenshots contain unreleased features, internal URLs, or API keys you haven't scrubbed yet.
Disclosure: I'm the developer of FileOnTap.
3. Keep text readable. For screenshots containing code or terminal output, compare the WebP against the PNG at 100% zoom. Code glyphs are unforgiving — if the anti-aliasing looks muddy, re-convert at higher quality. One careful check beats five blurry screenshots.
4. Reference them normally. GitHub's markdown renderer accepts .webp files in the repo or in issue attachments:
Nothing else changes. Your README syntax stays the same; only the bytes shrink.
A small repo hygiene checklist
- Never commit the originals and the WebP side by side unless you need the originals. Pick one format per asset and delete the other — repos accumulate dead images fast.
-
Put images under
docs/images/, not the repo root. Future you will thank present you. -
Name files after what they show (
onboarding-flow.webp), notScreenshot 2026-10-23 at 3.24.11 AM.png. - Re-export after UI changes. A WebP of last quarter's UI is worse than no screenshot at all.
Why "no upload" matters for docs screenshots
Documentation screenshots are uniquely sensitive: they show unreleased features, staging URLs, customer data in demo environments, and occasionally secrets someone forgot to redact. A converter that uploads every file to a server adds a leak vector to your release process. Converting in the browser — with a tool like FileOnTap — removes that vector entirely: the pixels never leave the machine that captured them.
Bottom line
GitHub renders WebP, PNG screenshots are heavy, and the fix is a two-minute conversion before you commit. Smaller screenshots mean faster READMEs, smaller repos, and happier contributors on slow connections. Keep the text sharp, keep the originals out of the repo, and never upload a screenshot you wouldn't post publicly.
