GitHub README Image Formats, Alt Text, Paths, and Folder Structure Explained
When a developer documents a web app, CLI tool, or API library, the right README image choice depends on the job of the image. A UI screenshot, command-output capture, architecture diagram, logo, workflow figure, and animated demo do not need the same format, path, or preview check.
This guide explains the practical decisions behind GitHub Markdown image syntax, README image alt text, relative image paths, and repository folder structure. The goal is simple: images should load reliably, explain the project, and remain readable after the next branch, folder, or documentation update.
Markdown image syntax and useful alt text
GitHub Markdown uses a familiar image pattern: . The text inside the brackets is not decoration. It is the short text alternative for people who cannot see the image, for contexts where the image fails to load, and for readers trying to understand the page quickly.
Good alt text describes what the image communicates. Instead of , write ![Settings page showing the API token field and save button] if that is the point of the image. For a diagram, describe the relationship: ![Worker queue diagram showing API requests moving through Redis to background jobs].
Relative image paths and repository folders
For images committed with your documentation, relative paths are usually the cleanest choice. Common patterns include docs/images/ for documentation figures, assets/ for general project assets, and .github/images/ for repository-profile or community files when that fits the project. Pick one pattern, document it, and use consistent filenames.
Relative paths are resolved from the Markdown file location. A root README can reference docs/images/install-flow.png. A Markdown file inside docs/setup.md may need images/install-flow.png or ../assets/install-flow.png depending on your folder structure.
docs/images/readme-dashboard-empty-state.png. Avoid spaces, screenshots named final-final.png, and names that only make sense on your desktop.Format decision table
| Image role | Best format | Path/storage recommendation | Main risk | What to preview |
|---|---|---|---|---|
| UI screenshot | PNG | docs/images/ or assets/readme/ | Oversized full-screen captures and unreadable labels. | Rendered width, text clarity, and dark-mode contrast. |
| Architecture diagram | PNG or SVG | docs/images/diagrams/ | Too many nodes or thin labels on mobile. | Phone-width readability and background contrast. |
| Command output | PNG, or real text when possible | Prefer Markdown code blocks if static text is enough. | Image text that cannot be copied or searched. | Whether a code block would serve readers better. |
| Logo or badge-like graphic | SVG or PNG | assets/ or badge service URL when appropriate. | Poor rendering or low contrast in themes. | Size, color, and legibility on light/dark backgrounds. |
| Animated demo | Short GIF, or video where supported for the context | docs/images/demos/ with a static fallback nearby. | Large file, long loop, reader distraction. | Loop length, crop, file size, and whether a still image is enough. |
| Photo-like project image | JPG | docs/images/ | Compression artifacts if the image contains text. | Edges, captions, and visual artifacts. |
PNG, JPG, SVG, GIF, and WebP in README work
PNG is usually the safest default for UI screenshots, terminal captures, diagrams, and images with text. JPG is practical for photo-like images but can damage code text and thin UI labels. SVG can be excellent for diagrams and logos because it scales cleanly, but preview it in GitHub and avoid external dependencies. GIF should be short, cropped, and purposeful.
WebP can be useful in many web contexts, but it may not be the safest default for every README or documentation workflow unless you have checked support for your target viewers and downstream docs tools. If your image might be reused in package registries, generated docs, learning platforms, or exported PDFs, PNG and JPG remain safer delivery formats.
Width, cropping, and captions
Image width should match the documentation purpose. A project overview screenshot can be wider than an inline command result, but neither should force the reader to zoom. Crop away browser tabs, bookmark bars, empty side panels, and unrelated terminal history. If the image needs context, add a sentence before or after it instead of embedding all explanation into the image itself.
Connect the decision to the full workflow
FAQs
No. Alt text should describe what the image communicates. A filename like diagram-v2.png does not tell a reader what the diagram means.
SVG can be a strong choice for vector diagrams and logos, but preview the rendered file, check contrast, and avoid relying on external resources. If the preview is inconsistent, export a PNG delivery copy.
Use a predictable repository folder such as docs/images, assets/readme, or another documented location. The important part is that the Markdown path resolves from the file that contains the image reference.
