Markdown links and images
Links and images share one syntax in Markdown. An image is a link with ! in front. This page covers both, plus the two things that cause the most trouble: relative paths and links to headings.
Inline links
Put the link text in square brackets and the destination in round brackets, with nothing between them.
Read the [CommonMark spec](https://spec.commonmark.org).Result:
Read the CommonMark spec.
Link titles
Add a title in quotes after the destination. Most browsers show it as a tooltip.
[GFM spec](https://github.github.com/gfm/ "GitHub Flavored Markdown")Result:
Autolinks
To show a URL and make it a link, wrap it in angle brackets.
<https://commonmark.org>Result:
GitHub Flavored Markdown (GFM) also links bare addresses that start with http://, https:// or www., without the brackets.
Reference links
A reference link splits the link in two. The sentence holds a label. A separate line, anywhere in the document, defines the destination for that label.
Both [CommonMark][cm] and [GFM] have a public spec.
[cm]: https://spec.commonmark.org
[GFM]: https://github.github.com/gfm/ "GitHub Flavored Markdown"Result:
Both CommonMark and GFM have a public spec.
The details:
[text][label]is the full form.[label]alone works when the link text and the label are the same.- Labels are not case-sensitive.
[gfm]and[GFM]match. - The definition lines do not appear in the rendered document.
- If no definition matches, the brackets stay visible as plain text.
Reference links keep long URLs out of your sentences, and you can reuse one definition many times.
Relative paths
A destination without a scheme such as https:// is a relative path. It starts from the folder of the file that contains the link.
| Destination | Points to |
|---|---|
setup.md |
A file in the same folder |
docs/setup.md |
A file in the subfolder docs |
../README.md |
A file one folder up |
/docs/setup.md |
A path from the root |
This page links to its neighbour with a relative path:
See also [Markdown tables](../markdown-tables/).Result:
See also Markdown tables.
What “root” means depends on the app. On GitHub, a path that starts with / begins at the root of the repository. In other apps, check your app. A destination cannot contain a plain space. Write <my notes.md> or my%20notes.md.
Links to headings
A destination that starts with # points to a heading on the same page.
Jump to the section on [alt text](#alt-text).Result:
Jump to the section on alt text.
The part after # is the heading’s anchor. Neither CommonMark nor the GFM spec defines these anchors. The app creates them. GitHub makes the heading text lower case, removes punctuation and replaces spaces with hyphens, so ## Alt text becomes #alt-text. If two headings have the same text, the later ones get -1, -2 and so on.
To link to a heading in another file, add the anchor to the path: docs/setup.md#install.
Images
The image syntax is the link syntax with ! in front. The text in square brackets is the alt text. A title is optional.
Result:
Image paths follow the same rules as link paths. Reference style works as well: ![alt][label].
Images as links
To make an image clickable, put the image inside the link text.
[](/)Result:
Alt text
Alt text describes the image in words. Screen readers read it out, and apps show it when the image cannot load.
- Say what the image shows and why it is there:
![Bar chart of downloads per month, rising since March]. - Keep it short. One sentence is usually enough.
- Do not start with “Image of”. The reader already knows it is an image.
- For a purely decorative image, leave it empty:
.
Alt text is plain text. Formatting inside the square brackets is not kept.
Where it works
Inline links, titles, angle-bracket autolinks, reference links and images are all CommonMark. They work in GitHub, GitLab, Obsidian, VS Code and every other app that follows CommonMark. Bare-URL autolinks come from GFM.
Relative paths and heading anchors are where apps differ. GitHub and GitLab resolve relative links and images between files in a repository. The VS Code preview follows relative links between files in your workspace. Obsidian has its own [[wikilink]] syntax next to standard Markdown links. For anchor names and root paths, check your app.
To read a Markdown file with its links and images in place, Markko shows .md files formatted on a Mac and in Quick Look.
FAQ
How do I link to a file with spaces in its name?
Wrap the destination in angle brackets, [notes](<my notes.md>), or replace each space with %20. A plain space ends the link destination.
How do I open a link in a new tab?
Markdown has no syntax for that. Where the app allows raw HTML, you can write an <a> tag with target="_blank". Otherwise the app decides how links open.
How do I change the size of an image?
Markdown has no syntax for image size. Where raw HTML is allowed, use an <img> tag with a width attribute. Some apps have their own size syntax, so check your app.
Why is my relative link broken?
A relative path starts from the folder of the file that contains the link, not from the folder you have open. Check for ../ steps, upper and lower case, and the file extension.