Images & embeds
How to Use an Image URL in Markdown READMEs and Docs
To show an image in Markdown, write an exclamation mark, alt text in square brackets, and the image URL in parentheses: . This guide covers getting a usable public image URL, writing good alt text, and knowing when a file committed inside the repository is more durable than any external link.
Updated
Get a public image URL
Markdown itself does not host images.
- Pick an image you own or have permission to publish, for example a public status graphic or an openly licensed illustration. Yoink links are public: anyone with the URL can open or forward the file, and sign-in does not change that.
- Open the Yoink uploader, choose Select Files or drag the image in, then start the upload with the main upload button and wait for it to complete.
- Copy the link from the completed result. It starts with
https://files.yoink.zip/. - Keep the original image on your machine. Public link lifetime is not guaranteed, so treat the hosted copy as a convenience, not your only copy. See limits and retention for details.
Write the image syntax
The GitHub Markdown syntax reference defines the image form as:
Replace the placeholder URL with your own copied link, and write alt text that actually describes the image. Alt text is what screen readers announce and what readers see if the image fails to load, so "green badge reading build passing" is useful while "image" is not.
Image versus plain link
The leading ! is the whole difference:
[Download the full-resolution diagram](https://files.yoink.zip/your-upload-path/diagram.png)The first line embeds the image inline. The second is a normal clickable text link. Pairing both is handy when the inline version is small and readers may want the original.
Prefer a committed file for durable READMEs
Any external image URL is a dependency on that link staying alive. For a README that should render correctly for years, the sturdier option is to commit the image into the repository and reference it with a relative path:
A relative path resolves relative to the Markdown file and follows the branch, so forks and tags keep working. Use an external files.yoink.zip URL for quick drafts, gists, chat, or platforms where you cannot commit assets, and keep the original image safe locally either way. There is no caching guarantee that would rescue a dead link later.
Preview before saving
- Open the image URL directly in a browser tab first. If the plain URL does not render there, Markdown will not fix it.
- Paste the Markdown into your editor and use the Preview tab (on GitHub, next to the Write tab) before committing or posting.
- Check the image appears at a sensible size and the alt text sits correctly in the sentence flow.
When the image does not show
Work through the common causes in order:
- Syntax: a missing
!, mismatched brackets, or a space between]and(breaks the embed. - Path and case: file names are often case-sensitive, so
Status.PNGandstatus.pngare different files. - Link health: open the URL in a private window.
- Renderer limits: some forums, chat apps, and documentation tools restrict or proxy embedded images, so valid Markdown can still render as plain text.
Browser handling also depends on the file's Content-Type and format support, which is one more reason to check the raw URL in a browser before debugging the Markdown itself.