Markdown Images and Alt Text
TL;DR
- Markdown image syntax is
. - In CommonMark, the image description becomes the HTML
altattribute when the image is rendered. - On GitHub, use relative links for images stored in your repository.
- Good alt text depends on the image's purpose: informative, decorative, functional, or complex.
What it is
An image in Markdown uses link-like syntax with a leading exclamation mark. The text inside the brackets is not a caption; it is the image description that becomes alt text in HTML output.
Why it matters
Images add context fast, but they can also hide meaning from readers who do not see them. Writing useful alt text makes your content more accessible and often makes your writing clearer for everyone.
Syntax
Minimal example
Source
What it does
This embeds an image and provides alt text of The team logo.
More examples
Example 1: Repository-relative image
What it does
This links to an image relative to the current Markdown file, which is usually the most maintainable approach for repository content.
Example 2: Decorative image with empty alt text
What it does
This creates an image with empty alt text. Use this only when the image is purely decorative and adds no information needed to understand the content.
Example 3: Functional image
[](./files/guide.pdf)
What it does
The image acts as a link. In this case, the alt text should describe the action or destination, not the button's appearance.
Example 4: Complex image
What it does
For a chart or diagram, the short alt text sets context, and the full explanation should appear nearby in normal text.
Common pitfalls
- Using the file name as alt text
- Why it happens: the file name is already available while writing
- Fix: describe the image's information or function instead
- Treating alt text like a visual caption
- Why it happens: both are attached to the image
- Fix: alt text should help someone who cannot see the image understand what matters
- Using empty alt text for informative images
- Why it happens: empty brackets are easy to type
- Fix: reserve empty alt text for purely decorative images
- Embedding repository images with absolute URLs when a relative path would do
- Why it happens: copied browser URLs feel convenient
- Fix: use relative links for repository images when your target platform supports them
- Using images of text when ordinary text would work
- Why it happens: screenshots and banners feel quick to reuse
- Fix: keep information as text unless the image is essential or a logo
Portability and platform notes
- Image syntax is core CommonMark and is defined as link syntax plus a leading
!. - In CommonMark, the image description is used as the HTML
altattribute when rendered. - GitHub supports images in issues, pull requests, discussions, comments, and
.mdfiles, and it recommends relative links for images stored in the same repository. - GitHub also supports the HTML
<picture>element. - Accessibility guidance does not depend on Markdown flavor: the right alt text depends on whether the image is informative, decorative, functional, or complex.
FAQ
Is the text inside ![ ] a caption?
No. In normal Markdown image syntax, that text becomes the image description used for the alt attribute in HTML.
What makes good alt text?
It depends on purpose. Informative images need a short description of the key information. Decorative images should usually have empty alt text. Functional images should describe the action or destination. Complex images often need brief alt text plus a fuller explanation nearby.
Should I use relative or absolute links for repository images?
Use relative links when the image lives in your repository and your target platform supports relative paths for that context.
Can I leave alt text blank?
Yes, but only when the image is purely decorative and contributes no information needed to understand the page.
Practice
- Add one informative image with meaningful alt text and one decorative divider with empty alt text.
- Replace a weak alt text like
screenshot.pngwith a description that explains what the reader actually needs from the image.
Related topics
- Links
- Relative links and repository paths
- Accessibility and inclusive Markdown writing
- HTML in Markdown and safety