Inserting Images
An image is written exactly like a link, with one extra character in front. That similarity is misleading, because the one extra character is where the real difference lives. A link is only useful when it is clicked, and the text that leads to it has to stand on its own; an image is often the entire content, and the text that replaces it when the image is unavailable has to carry the meaning on its own too.
That text is the alternative text — the word in square brackets. It is invisible in the normal case, yet it is the one part of the syntax that a reader depends on whenever the picture does not arrive. This page covers the syntax itself, how to write alternative text that is worth reading, how to point at a file that actually exists, and what to do when the image breaks anyway.
An exclamation mark, square brackets with the alternative text, round parentheses with the address, and an optional title in quotation marks:
<p><img src="https://example.com/demo.png" alt="Sample diagram" title="Optional title"></p>The shape matches an inline link exactly: the square brackets become the alt attribute, the parentheses become the src attribute, and the quoted title becomes the title attribute, which the browser shows as a tooltip on hover. The one thing that does not carry over is the exclamation mark, and it is the whole difference: drop it and the same brackets and parentheses produce a link instead of an image.
Images also accept the reference form from the previous page, with the exclamation mark in front of the reference:
![Sample diagram][demo]
[demo]: https://example.com/demo.png<p><img src="https://example.com/demo.png" alt="Sample diagram"></p>The alternative text does two jobs. When the file cannot be loaded, the browser puts the text where the image was, so the reader learns what they are missing. When a screen reader reaches the image, the text is the image — everything the reader gets is whatever is between the brackets. For that reason it is not a caption and not a label; it is the picture’s stand-in.
Two rules follow from that.
The first is to describe the content rather than the picture. For an architecture diagram, the useful alternative text names the parts and the relationship between them; the file name and the word “image” tell a screen reader user nothing they could not have guessed.
The second is that the alternative text is plain text. The characters between the brackets are not parsed as Markdown:
<p><img src="https://example.com/a.png" alt="Bold and code"></p>The emphasis marks and the backticks are stripped, and what remains is a single string. There is no way to emphasise part of an alternative text, because the alt attribute accepts a string and nothing else.
When to Leave It Empty
A purely decorative image — a divider, a background texture, a row of icons — may have empty alternative text:
<p><img src="https://example.com/divider.svg" alt=""></p>An empty alternative text tells a screen reader to skip the image, which is exactly right for decoration. If you would rather it be announced, give it a short description; if it really carries no information, empty is better than the word “image”.
The address of an image follows the same rules as the address of a link. Inside one repository, use a relative path; across sites, use a full address.
A relative path is resolved against the directory of the document that contains it. If a page lives in docs/guide/ and the picture lives in public/images/, the path from the page to the picture climbs two levels and then descends into the images directory:
<p><img src="../../images/lifecycle.png" alt="The request lifecycle"></p>The same picture is addressed differently from every other directory, which is the price of relative paths. Two alternatives avoid that maintenance. A root-relative path such as /images/lifecycle.png starts at the root of the site and stays correct wherever the page lives, as long as the file is served from the root. An absolute URL such as https://cdn.example.com/lifecycle.png is completely independent of the directory structure.
The image syntax has no size attributes at all — no width, no height, no alignment. Whatever the file measures, that is what the reader gets, and a 3000-pixel-wide screenshot arrives 3000 pixels wide. There are three ways to deal with that.
The first is to control the file itself: export the diagram at the width it should appear, or resize it before committing. The page then needs no markup at all, and the same image works in every renderer.
The second is HTML, which lets you state the dimensions directly:
<img src="../../images/lifecycle.png" alt="The request lifecycle" width="480" height="270">The width and height attributes are what the browser uses to reserve space before the file arrives, so the page does not jump around while the image loads. Keep the two numbers in the same proportion as the original file, or the browser squashes the picture to fit them. Note that the alt attribute is not optional in HTML either — the same accessibility requirement applies whether you write the image in Markdown or in raw HTML.
The third option is Mermaid, which is not an image file at all. A Mermaid block is a code block that the site draws as an SVG:
flowchart LR A[Order placed] --> B[Payment confirmed] B --> C[Stock reserved]
Because the diagram is vector graphics it stays sharp at any size and needs no separate file, and its width follows the container rather than a path. To stop it stretching across a wide screen, cap the width of the container in CSS instead of in the diagram source.
Markdown does not care where a file comes from, so a full URL to an image works exactly like a path in the repository:
<p><img src="https://cdn.example.com/dashboard.png" alt="A screenshot of the dashboard"></p>This is convenient for a quick sketch, and it is the wrong default for documentation. The moment the page depends on a third-party server, the picture’s lifetime is tied to that server’s uptime, its URL policy, and its anti-hotlinking rules — none of which you control.
A broken image is not a crash; it is a small, sad placeholder. The browser shows the alternative text in place of the picture, and if the alternative text is the word “image” then the reader learns exactly nothing about what was lost.
Two habits make this survivable. The first is to write alternative text that stands on its own, so that the fallback case is still a useful sentence rather than a label. The second is to keep the essential facts in the surrounding prose: a diagram should illustrate the text, not carry information that exists nowhere else. If a reader with images disabled would lose the point of the page, the page needs another sentence.
| Written as | What actually happens | Why |
|---|---|---|
 | An image | The basic form |
 | An image with empty alternative text | Empty alternative text is legal |
 | Alternative text reads “Bold” | The alt attribute only accepts plain text |
 | The path is encoded to %20 | Angle brackets around a path with a space |
[A diagram](https://x.com/a.png) | A link | The exclamation mark is what makes it an image |
. The exclamation mark must be there; without it the construct degrades into an ordinary link. - To make the image clickable, put a link around it: square brackets containing the image, then round parentheses containing the address. The link goes on the outside and the image on the inside.
- The relative path
../../images/flow.pngclimbs two levels out of the directory that holds the document and then descends into the images directory. - Check the result: the page shows an image inside a link, clicking it opens
https://example.com/docs/flow, and a failed load shows the descriptive sentence instead of an empty box.
Answer:
The diagram below shows the complete flow from placing an order to shipping it:
[](https://example.com/docs/flow)You should now be able to write an image with alternative text and a title, use the reference form for images, explain why the alternative text is plain text and why it must describe the content rather than the picture, place a picture with a relative path that resolves against the document’s own directory, and control the rendered size with HTML attributes or with a vector diagram. You should also be able to say what a reader sees when an image fails to load, and why keeping the essential facts in the prose matters more than keeping the image working. The last page of this chapter covers the form that needs no markup at all: URLs and email addresses that turn into links by themselves.