How to Prepare Screenshots and Diagrams for a GitHub README
When a SaaS team, student, or open-source maintainer prepares a README screenshot, the safest workflow is not "take a screenshot and commit it." It is source screenshot or design, remove private data, choose the right format, crop, compress carefully, save in a stable repository folder, add Markdown with useful alt text, and preview the README before publishing.
The process below keeps GitHub README images readable and maintainable without turning the repository into a collection of large, unreviewed screenshots.
Step 1: Decide what the image must explain
Write one sentence before creating the image: "This image shows..." If you cannot finish that sentence, the screenshot is probably decorative or too broad. Good README images explain a setup result, a UI state, an architecture relationship, a CLI command result, or a short product flow.
Step 2: Capture or design at a readable size
Use a clean browser window, readable zoom level, and a focused area of the interface. For diagrams, design with fewer nodes and larger labels than you would use in a slide deck. GitHub README preview is not a wall poster; it is a documentation surface that readers may open on laptops, tablets, and phones.
Step 3: Remove private data before optimization
Inspect the source screenshot for API keys, access tokens, email addresses, customer names, private repository names, internal dashboards, internal URLs, and terminal paths that reveal sensitive context. Redaction should happen before compression so the delivery copy never contains private details.
Step 4: Choose the format by image role
Use PNG for UI screenshots, diagrams, terminal output, and text-heavy documentation figures. Use JPG for photo-like images where exact text edges are not the priority. Use SVG for logos and clean vector diagrams when you can preview the result safely. Use animated GIF only for short motion that explains something a still image cannot.
Step 5: Crop away clutter
Remove browser tabs, bookmark bars, desktop background, terminal history, and unrelated panels unless they are part of the explanation. Cropping often reduces file size while improving clarity. It also helps readers focus on the exact feature, command, or flow your README is explaining.
Step 6: Compress carefully
Compression should make the delivery image lighter without damaging code text, UI labels, diagram lines, or command output. For PNG screenshots, compare the optimized copy with the source at the rendered README width. For JPG, look for artifacts around text and icons. If the optimized image makes setup harder to understand, the file is too compressed.
Step 7: Save images in a clear repository folder
Use a consistent folder such as docs/images/, assets/readme/, or another path your project already uses. Keep source design files separate if they are large or not needed by README readers. Name delivery images based on their role, for example docs/images/readme-install-success.png.
Step 8: Add Markdown image syntax with useful alt text
Use Markdown like . The alt text should describe the purpose of the image, not the file type or filename. Add nearby text if the image needs a longer explanation.
Step 9: Preview desktop and mobile widths
Preview the README after committing or before merging the branch. Confirm that the image loads, the relative path still works, the screenshot text is readable, diagrams do not become tiny on narrow screens, and transparent graphics remain visible in dark mode. If a diagram is too wide, split it into smaller figures.
Step 10: Keep the source for future updates
Keep the original capture, editable diagram, or design file somewhere appropriate for your team. The README should use the optimized delivery copy; the project should still be able to recreate the image when the UI, CLI output, or architecture changes.
Repeatable README image workflow
| Stage | Action | Quality check |
|---|---|---|
| Plan | Define what the image must explain. | The README still makes sense if the image is supported by nearby text. |
| Prepare | Capture, crop, redact, and choose the format. | No private data remains and text is readable. |
| Optimize | Create a delivery copy for the README. | Compression did not damage labels, code, or diagrams. |
| Publish | Save in a repo folder and add Markdown with alt text. | The relative image path works from the Markdown file location. |
| Verify | Preview on GitHub before merging. | Desktop, mobile width, and dark mode remain usable. |
FAQs
Commit the optimized delivery copy for the README. Keep original captures or editable diagrams separately when your team needs them for future updates.
Check the image purpose, private data, format, crop, compression quality, repository path, alt text, desktop preview, mobile-width preview, and dark-mode contrast.
Not always. If the content is static command output or code that readers may copy, real Markdown text or a code block can be more useful than an image.
