An image brings a page to life. In Markdown, the syntax for an image looks almost identical to a link — with just one extra character at the very start. Once you have written a few links, images feel completely familiar.

What You Will Need

Your Markdown editor, open and ready. For the later steps in this workflow, you will also need an image file — a photo saved on your computer, or a photo hosted somewhere on the web. If you do not have one yet, you can read through the examples and come back with an image when you are ready.

Note: the Output panels in this workflow show placeholder text where images would appear. Once you have a real image file, replace the filename in your Markdown and the image will show.

Workflow

Step 1

Aim: write the image syntax.

An image starts with an exclamation mark (!), followed by a short description inside square brackets, followed by the image filename (or web address) inside round brackets. Compare it to a link:

A link: [link text](address)
An image: ![description](filename)

The exclamation mark is the only difference.

Try

MARKDOWN

![A sunny garden with roses in full bloom](garden-roses.jpg)

If the image file exists in the right place, it appears in your preview. If not, the description text appears in its place — which is exactly the intended fallback behaviour.

Output

[Image placeholder — replace garden-roses.jpg with a real image file to see the photo here]

Step 2

Aim: understand why the description matters.

The text inside the square brackets is called alt text — short for 'alternative text'. It serves two important purposes:

It describes the image to anyone who cannot see it, including people using screen readers and anyone reading a printed copy of your document.
It appears in place of the image if the file fails to load.

Write alt text as a short, accurate description of what the image actually shows — not its filename, and not a vague label like 'photo'. Write it as if you were describing the image to someone over the phone.

Try

MARKDOWN

![A golden retriever sitting in a field of daffodils on a bright spring morning](dog-in-daffodils.jpg)

Output

[Image placeholder — replace dog-in-daffodils.jpg with a real image file]

Alt text that would be read aloud: 'A golden retriever sitting in a field of daffodils on a bright spring morning'

Step 3

Aim: use an image from the web.

If you have a web address for an image — rather than a file saved on your computer — you can use that address directly in place of a filename. The syntax is identical.

Try

MARKDOWN

![REPLACE: describe your chosen web image here](REPLACE: paste the full web address of your image here)

To find a web address for an image: right-click on any image in your browser and choose 'Copy image address' or 'Copy image link'. Paste that address into the round brackets.

Using web-hosted images works well for quick tests and personal notes. For anything you plan to publish, it is better to save your own copy — web addresses can change or disappear without warning.

Output

[Image placeholder — paste a real web image address into the round brackets to see the image here]

Step 4

Aim: place an image in context, with a caption.

Markdown does not have a built-in caption feature, but a short italic line immediately beneath an image acts as one in practice. This is a widely understood convention and looks clean in most renderers.

Try

MARKDOWN

## Our Garden in May

![REPLACE: describe your garden photo here](REPLACE: your-garden-photo.jpg)

*REPLACE: write a short caption for the photo here — for example: The roses along the south fence, taken on the first warm Saturday of the month.*

The warm spell in early May brought everything out at once. The roses along the fence were the real surprise — we planted them only last autumn and did not expect them to flower so well in their first year.

Output

Our Garden in May

[Image placeholder — add your garden photo file to see it here]

REPLACE: your caption goes here

The warm spell in early May brought everything out at once. The roses along the fence were the real surprise — we planted them only last autumn and did not expect them to flower so well in their first year.

Step 5

Aim: review the image syntax.

The image syntax is easy to remember once you see the relationship with links:

A link: [text the reader sees](where it goes)
An image: ![text if image is missing](the image file)

A few things to keep in mind:

The image file must exist in the right location for the preview to show it
Alt text should describe what is in the image, not just name the file
An italic line immediately beneath the image makes a clean, readable caption
When your images are ready, replace the placeholder filenames with your actual file names

Try

MARKDOWN

# My May Garden Diary

## Week One

![REPLACE: describe the first photo here](REPLACE: week-one-photo.jpg)

*REPLACE: caption for week one photo*

The garden is waking up slowly. The tulips I planted in October are finally showing colour, and the herb patch is starting to look useful again.

---

## Week Two

![REPLACE: describe the second photo here](REPLACE: week-two-photo.jpg)

*REPLACE: caption for week two photo*

A much warmer week. Everything that was thinking about flowering has now decided to get on with it.

Output

My May Garden Diary

Week One

[Image placeholder — add week-one-photo.jpg to see it here]

REPLACE: caption for week one photo

The garden is waking up slowly. The tulips I planted in October are finally showing colour, and the herb patch is starting to look useful again.

Week Two

[Image placeholder — add week-two-photo.jpg to see it here]

REPLACE: caption for week two photo

A much warmer week. Everything that was thinking about flowering has now decided to get on with it.

Images are ready whenever you are — just swap the placeholder filenames for your real ones and they will appear. The next workflow covers blockquotes: a simple way to set off a quotation, a highlight, or a tip from the rest of your text.