Markdown Image Syntax: Add Images and Fix Broken Links

Markdown images use an exclamation mark followed by a description in square brackets and an image address in parentheses. The fastest way to debug a missing image is to check the address before changing the surrounding document.

A copyable image example

![Architecture diagram showing the browser and API](https://example.com/images/architecture.png)

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:

![API request flow](https://example.com/images/request-flow.png "Request flow")

To make the image a link, wrap the image expression in an ordinary Markdown link:

[![Project overview](https://example.com/images/overview.png)](https://example.com/project)

These patterns are covered in the Markdown Guide image reference.

Local paths need the right context

![System overview](./images/system-overview.png)

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.

A practical broken-image checklist

1. Open the exact image URL directly. Check for an image rather than a login page or a file preview page.
2. Compare spelling and capitalization with the stored filename.
3. Remove accidental spaces around the address and check that both parentheses are present.
4. If the address contains spaces, use a URL with encoded spaces or rename the file.
5. Check whether a temporary signed URL has expired.
6. Preview the full document again after changing one reference.

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.

Image size and captions

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.

Preview before sharing

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.