Markdown links and images use almost identical syntax: a link is [text](url), and an image is the same thing with an exclamation mark in front, . This guide walks through inline, reference and automatic links, how to add titles and alt text, and what to do when a link or picture will not show.
Key takeaways
- Links use square brackets for the text and parentheses for the address.
- Images add a leading
!and use the bracket text as alt text. - Reference-style links keep long URLs out of your paragraphs.
- Always write useful alt text and descriptive link text.
Inline Links
The inline link is the form you will use most. Put the visible text in square brackets and the destination right after it in parentheses, with no space between them. For further insights on Markdown formatting, check out goportugal.net for detailed examples.
Read the [Markdown syntax guide](https://daringfireball.net/projects/markdown/syntax).
You can add a tooltip title in quotes after the address. Browsers usually show it when you hover over the link.
[Markdown home](https://daringfireball.net/projects/markdown/ "Original Markdown page")
Links can point to other files in the same project, such as [setup notes](docs/setup.md), or to a spot on the same page, such as [jump to FAQ](#faq). Anchor names are generated differently from tool to tool, so confirm the anchor format your editor or site uses.
Good link text describes the destination. Writing [read the pricing policy](policy.md) helps readers and screen reader users far more than [click here](policy.md), because people often scan a list of links without the sentence around them. Search engines also use link text as a clue about the target page, so a clear phrase helps there too. Keep it short, and avoid wrapping an entire sentence in a link.
Reference-Style Links
When a paragraph holds many long addresses, reference links keep the text readable. You write a label in the paragraph and define the address elsewhere, usually at the bottom of the file.
Visit the [style guide][guide] before you publish.
[guide]: https://example.com/style-guide "Team style guide"
Labels are not case sensitive, and you can reuse one label several times. This also means that if a URL changes you fix it once.

Automatic Links and Plain URLs
Wrap a web address or an email address in angle brackets and Markdown turns it into a clickable link whose text is the address itself.
<https://example.com>
<hello@example.com>
Some flavors, including GitHub Flavored Markdown, also link bare URLs automatically. Core Markdown does not guarantee that, so use angle brackets when you want it to work everywhere.
How to Add Images in Markdown
- Put the picture file where your project or platform can reach it, or copy its web address.
- Type an exclamation mark, then square brackets holding a short description of the picture.
- Add the file path or URL in parentheses straight after the brackets.
- Optionally add a title in quotes after the path.
- Preview the page to make sure the picture loads.

The text inside the brackets becomes the alt attribute in HTML. It is read aloud by screen readers and displayed if the picture fails to load, so describe what the image shows instead of writing “image” or the file name.
Markdown Links and Images Together
To make a picture clickable, wrap the whole image syntax inside a link:
[](https://example.com/report.pdf)
Core Markdown has no way to set image width or alignment. If you need that, many tools accept inline HTML such as <img src="photo.jpg" width="400" alt="Description">, although some platforms strip it. The MDN page on the HTML img element lists the attributes you can use.

Troubleshooting Broken Links and Pictures
| Symptom | Likely cause | Fix |
|---|---|---|
| Link shows as plain text | Space between ] and ( |
Remove the space |
| Link breaks at a bracket or parenthesis in the URL | Special characters | Encode them (%28, %29) or wrap the URL in angle brackets |
| Image shows a broken icon | Wrong path or file not uploaded | Check the relative path and filename case |
| Image is too large | No size control in Markdown | Resize the file or use HTML |
| Link opens in the same tab | Markdown has no target option | Use HTML if the platform allows it |
For a broader overview of the symbols around links, see the Markdown cheat sheet. When you need to carry these elements into a word processor, converting Markdown to Google Docs explains how links and pictures behave, and converting Markdown to HTML shows the underlying tags.
Frequently Asked Questions
Can I open a Markdown link in a new tab?
Not with Markdown syntax alone. Some platforms add this behavior themselves, or you can write the link in HTML where it is allowed.
Do image paths have to be full URLs?
No. Relative paths such as images/photo.png work when the file sits next to your document or project.
What should I write as alt text?
One short sentence that tells a person who cannot see the image what it shows or why it is there.
Can I use spaces in file names?
It is better to avoid them. Use hyphens, or encode spaces as %20 or wrap the path in angle brackets in CommonMark.
How do I link to a heading in the same document?
Use a hash plus the heading’s anchor, like [see below](#troubleshooting). How anchors are generated depends on the tool.
Wrap-Up
Once you remember that an image is a link with an exclamation mark, the rest follows. Keep link text meaningful, write real alt text and preview before publishing, since support for extras varies between editors.



