To display an image in Markdown, write . To link to an image without displaying it, write [View image](image-url). To make the displayed image clickable, wrap the image syntax in a link.
| What the reader sees | Markdown example |
|---|---|
| A text link to the image | [View diagram](https://example.com/diagram.png) |
| The image inside the document |  |
| A clickable image | [](https://example.com/project) |
Replace these example addresses with real destinations. The exclamation mark determines whether Markdown embeds the image or displays a text link. The outer link in the third example controls where a click goes; use the full-size image URL there if the reader should open the original image.
For ordinary website hyperlinks and README file links, see the Markdown link syntax reference. The examples below focus on images and their addresses.

Replace the example address with a real image URL. The bracketed text is alternative text: describe the information the image conveys rather than its filename. You can also add an optional title:

To make the image a link, wrap the image expression in an ordinary Markdown link:
[](https://example.com/project)
These patterns are covered in the Markdown Guide image reference.
A Markdown image from a URL needs an address that returns the image itself. A gallery page, a repository file preview, or a cloud-storage sharing page usually returns HTML instead. Opening that address successfully in a browser does not prove it can be embedded as an image.
For example, a GitHub URL containing /blob/ opens the file's web page. Use the image's Raw link and copy the resulting address into the image syntax; GitHub explains this in its file viewing documentation. Keep the leading !: [diagram](URL) creates a text link, while  embeds an image. For text links and linked images, see Markdown link syntax.
Before sharing the document, check the final address:
Use an HTTPS address for a shared web document. Do not put a private access token or password into the Markdown URL. If the image needs authentication, choose a sharing workflow that gives the intended readers access rather than making private material public just to render it.

This path needs a viewer that can resolve the referenced file. Sharing a Markdown file alone does not automatically upload its image folder. Before sharing, put the image at an accessible HTTPS URL and update the reference, or use a workflow that packages the document and its assets together.
Think about the reader's environment. A path that works on your laptop may point nowhere in a browser. A private storage URL may load for you because you are signed in, while a colleague sees an access error. Test the address in a private browser window to check the intended sharing experience.
Suppose the image stays in the project’s images folder, but you move the document from the root into docs.
project/
├── docs/
│ └── README.md
└── images/
└── overview.png
| Markdown file location | Image syntax |
|---|---|
project/README.md |
 |
project/docs/README.md |
 |
In the second example, ../ goes up from docs to the project root before looking in images. Check the path from the Markdown file’s new location, use forward slashes, and match the image filename’s case. If the file is on GitHub, confirm the image is committed on the branch you are viewing. GitHub’s relative path documentation
If the repository preview works but the shared copy does not, open the shared copy as a reader. A standalone share needs its own accessible image address, such as an HTTPS URL to the image itself.
Do not replace every image at once. Start with one small, known-good image so you can distinguish an address problem from a document-wide rendering problem.
Basic Markdown image syntax does not define a portable width setting. HTML image tags and renderer extensions can offer sizing, but support depends on the viewer. For a document you expect to share across tools, prepare the image at a sensible size and add a caption as ordinary text underneath it.
A useful caption explains what the reader should notice. For an architecture diagram, that might be the boundary between public and private services; for a screenshot, it might identify the button the reader needs.
Open the Markdown in mdview.io and check the surrounding heading, image, and caption together. For documents with diagram source, see Markdown preview with Mermaid. Keep the original Markdown so you can update the address if the image moves later.