GitHub Markdown Image Generator
Add images to GitHub READMEs with sizing, centering, and dark/light mode variants
Relative paths (assets/logo.png) work inside the repo; raw.githubusercontent.com URLs work everywhere.
Generates a <picture> element that swaps images with the viewer's color scheme.
<img alt="Project logo" src="https://raw.githubusercontent.com/user/repo/main/assets/logo-light.png" width="400">
Relative Paths vs raw.githubusercontent.com URLs
There are two ways to reference an image committed to your repository. A relative path like assets/screenshot.png is resolved by GitHub against the location of the README itself, so it keeps working when the repo is forked, renamed, or browsed on a different branch. An absolute URL of the formhttps://raw.githubusercontent.com/user/repo/main/assets/screenshot.pngpoints at GitHub's raw file CDN and renders anywhere — on npm, PyPI, documentation sites, or blog posts that reuse your README. Prefer relative paths inside GitHub and raw URLs when the Markdown leaves GitHub.
Sizing and Aligning Images with <img>
GitHub-flavored Markdown has no syntax for image dimensions and strips style attributes, but it does allow a safe subset of HTML. The width attribute on an<img> tag is the standard way to shrink a large screenshot, and the legacy align attribute floats an image left or right so text wraps around it. To center an image, wrap it in<p align="center">— modern CSS is filtered out, but this old-school attribute survives GitHub's sanitizer.
Dark Mode and Light Mode Images
A logo designed for a white background can disappear when a visitor views your README in dark mode. GitHub supports the HTML <picture> element withprefers-color-scheme media queries, letting you serve a different image for each theme. A simpler Markdown-only alternative is appending#gh-dark-mode-only or#gh-light-mode-only to two image URLs — each image is then shown only in the matching mode. The picture element is the more robust choice because it also works in gists and on github.dev.
The Drag-and-Drop Upload Trick
You don't always need to commit an image to get a URL. Drag any image into a GitHub issue, pull request description, or comment box, and GitHub uploads it to its user-content CDN and inserts the finished Markdown for you. Copy that generated URL and you have a permanently hosted image you can reuse in your README — a popular shortcut for screenshots and GIFs you don't want cluttering the repository history.
Badges vs Images
Both badges and screenshots are technically images, but they serve different jobs. Badges are small dynamic SVGs — build status, package version, license, code coverage — that update automatically because the URL points at a service like shields.io. Regular images are static assets you control. A polished README typically opens with a centered logo, follows with a row of badges, and shows screenshots or GIFs further down.
Frequently Asked Questions
How do I add an image to a GitHub README?
Commit the image to your repository (a docs/ or assets/ folder is common), then reference it with a relative path: . GitHub resolves the path relative to the file containing the Markdown.
How do I resize an image in GitHub Markdown?
GitHub ignores any size hints in Markdown syntax, so use an HTML img tag instead: <img src="assets/logo.png" alt="Logo" width="300">. Setting only the width keeps the aspect ratio intact.
How do I center an image in a GitHub README?
Wrap the img tag in a paragraph with the align attribute: <p align="center"><img ...></p>. GitHub strips modern CSS but still honors the legacy align attribute, which is why this pattern works.
How do I show a different image in GitHub dark mode?
Use the HTML picture element with source tags whose media attribute matches prefers-color-scheme, or append #gh-dark-mode-only / #gh-light-mode-only to two separate Markdown image URLs. This generator outputs both patterns.
Should I use a relative path or a raw.githubusercontent.com URL?
Use relative paths inside your own repository — they survive forks, renames, and branch changes. Use the absolute raw.githubusercontent.com URL when the image must render outside GitHub, such as on npm, PyPI, or another site.
What is the drag-and-drop upload trick for GitHub images?
Drag an image into any GitHub issue, pull request, or comment box and GitHub uploads it to its CDN, inserting ready-made Markdown. Many people open a draft issue just to generate a hosted image URL for their README.
When should I use a badge instead of an image?
Badges (from shields.io and similar services) are dynamic SVG images that show live data like build status, version, or coverage. Use a badge for status information and a regular image for screenshots, logos, and diagrams.