Adding Screenshots to Your README

Adding Effective Screenshots to Your README

Screenshots transform a wall of text into an engaging README. For web applications, desktop tools, and CLI tools with visual output, screenshots are often more convincing than any amount of written description.

Image Hosting Options

GitHub Repository (Recommended)

Store screenshots in a docs/ or .github/ directory:

![Dashboard](./docs/screenshots/dashboard.png)

This keeps images versioned alongside code and never breaks due to external hosting issues.

GitHub Issue Trick

Drag an image into a GitHub issue comment to get a permanent URL. You don't need to submit the issue. This is useful for quick one-off screenshots.

Markdown Image Syntax

Basic image:

![Alt text](url)

Image with link (clicking opens full size):

[![Alt text](thumbnail-url)](full-size-url)

Image Sizing with HTML

Markdown doesn't support image sizing, but HTML does:

<img src="./docs/screenshot.png" alt="Dashboard" width="600">

For responsive centering:

<p align="center">
  <img src="./docs/screenshot.png" alt="Dashboard" width="80%">
</p>

Dark and Light Mode

If your app supports both themes, show both:

<p>
  <img src="./docs/light-mode.png" alt="Light mode" width="49%">
  <img src="./docs/dark-mode.png" alt="Dark mode" width="49%">
</p>

Animated GIFs and Videos

For interactive features, a GIF is worth a thousand screenshots:

• Use tools like LICEcap (macOS/Windows) or peek (Linux) to record GIFs
• Keep GIFs under 10MB for fast loading
• Show real workflows, not just static screens

Screenshot Checklist

• Use realistic data (not "Lorem ipsum" or "Test User")
• Blur or redact any personal information
• Capture at a consistent window size
• Include the browser chrome for web apps (or crop it consistently)
• Optimize file size (TinyPNG, ImageOptim)
• Add alt text for accessibility