README Screenshots: Keep Them as Files in /docs

A README screenshot taken with Win+Shift+S is on the clipboard and nowhere else. If the user pastes it into a Markdown file in an editor that does not auto-save pasted images, the image is gone the next time the clipboard clears. If the user pastes it into a GitHub comment through the web UI, GitHub uploads the image to its asset CDN and produces a URL — that URL works in the comment, but the image is not part of the repository, and a fork or a clone does not get the asset. The right pattern for an open-source maintainer is to save the screenshot as a file in a /docs folder, commit it, and reference it by relative path. This guide covers that workflow and the trade-offs of the alternatives.

For neighbouring topics, see SQL clients: result grids to clipboard, code review comments: stage before you submit, and best clipboard habits for developers in 2026. For the underlying clipboard limits, see Windows clipboard settings, line by line and Windows clipboard 4 MB cap: what gets dropped.

The problem with clipboard-only screenshots

The Windows clipboard holds 25 items in history and caps each item at 4 MB. A screenshot of a 1080p window, as a PNG, is typically 200-600 KB. A 4K screenshot is 1-3 MB. A multi-monitor screenshot can exceed 4 MB and be silently dropped from history. The clipboard stores bitmap, text, and HTML formats; PNGs are carried as bitmap (DIB) and converted on paste.

Three failure modes follow:

• The image was never saved. Win+Shift+S places the snip on the clipboard but does not save a file. If the user pastes into a destination that does not auto-save, the image is lost when the next copy overwrites the clipboard.
• The image is too large for history. A snip over 4 MB does not appear in Win+V history. The user can still paste it once, immediately, but cannot re-paste it from history.
• The image lives on a third-party CDN. Pasting into GitHub's web comment box uploads to user-images.githubusercontent.com. The URL works in the comment, but the asset is not in the repository.

The third failure mode is the most insidious. A fork of the repository preserves the Markdown but not the CDN-hosted images. If the CDN URL changes or the account is deleted, the README loses its screenshots. For an open-source maintainer, this is the failure to design against.

The right structure

A repository that takes documentation seriously has a /docs folder, and inside that folder an images/ folder (or assets/, static/ — pick one and stick with it). Screenshots live in docs/images/. The README references them by relative path:

![Main window](docs/images/main-window.png)

The path is relative to the repository root, not to the README file. Most Markdown renderers, including GitHub's, resolve the relative path correctly.

A typical structure:

repo/
├── README.md
├── docs/
│   ├── images/
│   │   ├── main-window.png
│   │   ├── settings-panel.png
│   │   └── drag-drop-demo.png
│   ├── architecture.md
│   └── contributing.md
└── src/

Naming the screenshots descriptively (main-window.png, not screenshot-01.png) makes them findable in git log and in the repository's file list. The name should describe what the screenshot shows, not when it was taken.

Choosing a format

PNG is the default for screenshots. It is lossless, supports transparency, and is widely supported. For most UI screenshots, PNG is the right choice.

JPEG is smaller but lossy, and the artefacting is visible on text. Do not use JPEG for screenshots that contain code or UI text. WebP is supported by modern browsers and produces smaller files, but some older image viewers do not render it.

GIFs for animations are a separate concern. For a README demo, a short MP4 or WebM is usually better than a GIF: smaller file, higher quality, and the README renders it inline with <video> tags. GitHub supports both.

The capture workflow

The workflow that produces a committed screenshot, end to end:

1. Capture with Win+Shift+S or Snipping Tool. Win+Shift+S places the snip on the clipboard. Snipping Tool, in its modern Windows 11 form, can also save directly to a file.
2. Save to the docs folder. The fastest path is Snipping Tool's "Save As" dialog. If the snip is on the clipboard only, open an image editor (Paint, Paint.NET, Photoshop) and paste, then save as PNG to docs/images/.
3. Reference in the README. Use the relative path syntax ![Alt text](docs/images/filename.png).
4. Commit the image and the README change together. The commit that adds the screenshot should also add the reference; otherwise, the README points at a file that does not exist in that revision.
5. Push. The screenshot is now part of the repository and survives forks, clones, and CDN outages.

For a screenshot that will be reused across multiple Markdown files, put it in docs/images/ once and reference it from each file with the same relative path.

The GitHub web uploader as a fallback

When a maintainer is editing a README directly on GitHub's web interface (for a quick fix, or because they are on a machine without a local clone), GitHub's image uploader is acceptable as a fallback. Drag the image into the editor, GitHub uploads it to its CDN, and the editor inserts a URL like https://user-images.githubusercontent.com/.../screenshot.png.

The catch: the URL is not part of the repository. If the maintainer wants the screenshot to be in the repo, they should replace the URL with a relative path and commit the image file in a follow-up commit from a local clone.

The GitHub CDN URLs are stable in practice — GitHub has not deleted user-uploaded images — but they are tied to the user account that uploaded them. If the account is deleted, the images go with it. For a project that is meant to outlive any single maintainer, this is a fragility worth removing.

Image size and clone weight

A repository with 50 screenshots at 500 KB each is 25 MB of binary assets. This is not catastrophic, but it does bloat the clone. Two patterns help:

• Keep screenshots small. Crop to the relevant region before saving. A 1920x1080 screenshot of a settings panel that occupies the centre 800x600 pixels should be cropped to 800x600 before commit.
• Use a Git LFS track for large assets. Git LFS stores large files outside the repository and replaces them with pointer files in the commit history. This keeps clones fast. The trade-off is that LFS is a separate service with its own bandwidth limits.

For most small-to-medium open-source projects, neither is necessary. Keep screenshots cropped, keep them PNG, and the repository stays manageable. For a project that ships video tutorials or large diagrams, LFS is worth setting up.

Reusing screenshots across projects

A screenshot that lives in one repository is not reusable in another without either a copy or a submodule. For a portfolio of related projects that share screenshots (for example, a set of tools that all screenshot the same workflow), the patterns are:

• Copy the screenshot into each repo. Simple, but the screenshots drift over time as one repo updates and the other does not.
• Use a shared assets repository as a Git submodule. The screenshot lives in assets-repo/images/, and each project submodules it. Updates happen once.
• Use absolute URLs to a stable CDN. For example, a screenshot hosted on the project's documentation site. The screenshot is not part of the repo, but the URL is stable as long as the docs site is up.

The submodule approach is the most maintainable for a portfolio; the copy approach is the simplest for a one-off.

When the screenshot should not be in git

Not every screenshot belongs in a repository. A screenshot that is a one-off for a bug report — for example, a screenshot of a crash dialog attached to a single issue — should be attached to the issue, not committed to the repo. GitHub issues have their own attachment uploader, and the screenshot is part of the issue's history, not the codebase's history.

The distinction: if the screenshot documents the current behaviour of the code (a UI demo, a settings panel), it belongs in /docs. If the screenshot documents a specific bug at a specific point in time, it belongs in the issue.

For more on what belongs in git versus what belongs on the clipboard, see when a screenshot belongs in git, not in history and how to keep the last ten screenshots handy.

A staging workflow with a clipboard shelf

A maintainer revising a README often takes several screenshots in one sitting: main window, settings panel, drag-drop demo, before/after comparison. The workflow that avoids re-taking screenshots:

1. Take all screenshots with Win+Shift+S. Each goes to the clipboard; Win+V history holds the recent ones.
2. Open an image editor and paste each screenshot from history, saving to docs/images/ as a named PNG.
3. Update the README references in one edit.
4. Commit the images and the README together.

A clipboard shelf that holds images side by side can speed up step 2 — the maintainer drags each image from the shelf into the editor — but the underlying workflow is the same: capture once, save to file, reference by path. For more on this pattern, see how to keep a repro command next to its screenshot.

A short checklist

• Save screenshots to docs/images/ with descriptive names.
• Reference by relative path in the README.
• Commit image and README change together.
• Prefer PNG for UI; JPEG only for photo-like content.
• Crop before committing; clone weight matters.
• Use GitHub's web uploader as a fallback, but migrate to a relative path in a follow-up commit.

Related reading

• Code Review Comments: Stage Before You Submit
• The .env File Should Never Touch History
• Best Clipboard Habits for Developers in 2026
• Clipboard Tools on Multi-Monitor Windows Setups

Sources

• GitHub Docs — Basic writing and formatting syntax — official GitHub documentation for image references in Markdown, including the relative-path syntax used in READMEs
• GitHub Docs — Attaching files — official guidance for the web uploader, which produces CDN URLs that are not part of the repository
• Microsoft Support — Capture a snip with Snipping Tool — official Snipping Tool documentation, including the Save As dialog used to write screenshots directly to a /docs folder
• Microsoft Learn — Clipboard formats (Win32) — official list of clipboard formats, including CF_DIB, which is how a screenshot is carried before being saved to a file
• Git LFS — Documentation — official Git Large File Storage documentation, used to keep large screenshot and video assets out of the main repository history

Copy. Stack. Drop.

Transform your clipboard into an interactive edge shelf. Stack, pin, and drag assets into any app with zero friction.

Download for Windows Get from Microsoft Store

How to Install Guide · First 10 Minutes Guide · Drag & Drop Guide · Edge-Drop vs Win+V · Support