Screenshots for GitHub READMEs & Documentation

Make the first screen count

Visitors to a repository decide quickly whether a project looks maintained and usable. A clear hero screenshot with balanced padding and a consistent frame signals care. Keep the interface legible: crop to the essential area and export at 2x so text stays readable when GitHub scales the image down.

Transparent backgrounds also work well because they adapt to both GitHub's light and dark themes.

Social preview image

GitHub lets you set a repository social preview, and Open Graph cards drive how links look on X, Slack and Discord. The 1200×630 aspect ratio in ScreenshotBeautifier matches that format exactly, so you can place your product on a gradient and export a ready-to-upload card.

Keep key content away from the edges, since some platforms crop slightly.

Docs that stay consistent

Use the terminal frame for CLI output and a browser or window frame for web and desktop tools. Save one preset for your project and reuse it across the README, docs site and release notes. When the UI changes, batch export refreshes every image in one go.

Remember to redact tokens and personal paths before committing images to a public repository.

What makes a good README screenshot

A good README image answers three questions in a glance: what does this project do, what does it look like when it works, and is it maintained. Show a real, populated state rather than an empty screen, keep unrelated UI out of the frame, and make sure the text is readable at the width GitHub displays, which is roughly 800–900 pixels on desktop.

For libraries without a UI, show the terminal output or a rendered result instead. A short CLI session with a clear command and output often communicates more than a paragraph of text.

Light and dark theme support

GitHub supports light and dark themes, and images with opaque white backgrounds can look jarring in dark mode. Options include using a transparent background with a frame that reads well on both, using a mid-tone gradient that works on either theme, or providing two images and switching them with the picture element and the prefers-color-scheme media query in your README.

Whichever you choose, test the README in both themes before publishing.

Organising images in your repository

Keep images in a dedicated folder such as docs/images or assets, name them descriptively (for example cli-output.png rather than image1.png), and add alt text in your Markdown so that the README remains understandable to screen reader users and to search engines. Avoid committing very large files: WebP or compressed PNGs keep the repository lean and the README fast to load.

Reference images with relative paths so they still work in forks and mirrors.

Beyond the README

The same style carries over to your documentation site, package registry pages, release notes, blog posts and conference talks. Consistency makes the project feel cohesive. When the interface changes, run a batch export and replace the images in one commit.

Remember that public repositories are permanent in practice. Before committing any screenshot, check it for tokens, personal paths, private URLs and customer data.

How to do it in 4 steps

1. Capture the key screen of your project.
2. Apply a window or terminal frame with modest padding.
3. Choose a transparent or subtle background and export at 2x.
4. Use the 1200×630 ratio for a repository social preview.

Frequently asked questions