Markdown Links & Images: The Complete Guide to Adding Links, Images, and References

Links and images are the building blocks that turn plain text into rich, navigable content. Without links, your document is an island. Without images, it is a wall of text. Together, they make Markdown documents interactive and visually engaging.

This guide covers every way to add links and images in Markdown — from the basics to advanced techniques like reference-style links, clickable images, and footnotes.

Links in Markdown

Links are the backbone of the web — and Markdown makes adding them effortless. Markdown supports three types of links: inline, reference-style, and auto-links. Each has its use case.

Pro tip: Use the MarkdownMaster Editor to experiment with links in real time — every change updates the preview instantly.

Inline Links

The most common link format. Wrap the link text in square brackets, then the URL in parentheses:

This is an [inline link](https://markdownmaster.site/editor/) to our editor.

Rendered: This is an inline link to our editor.

You can also add a title (shown on hover) by adding a quoted string after the URL:

[MarkdownMaster](https://markdownmaster.site "Free Markdown Editor")

Reference-Style Links

Reference-style links keep your text clean by separating the link text from the URL. This is especially useful for long documents where the same URL appears multiple times:

Check out [MarkdownMaster][mm] for a free editor.

[mm]: https://markdownmaster.site/editor/

The [mm] reference can be defined anywhere in the document — typically at the bottom. This keeps your paragraphs readable without long URLs interrupting the flow.

Reference definitions are case-insensitive and can contain letters, numbers, spaces, and hyphens. These are all equivalent:

[link text][1]
[link text] [1]
[link text][A1]
[link text][a1]

Auto-Links

For URLs and email addresses that you want to display as-is (and make clickable), wrap them in angle brackets:

Most renderers will turn these into clickable links automatically. Some renderers also auto-link bare URLs without angle brackets, but using angle brackets is the safe, portable approach.

Images in Markdown

Image syntax is almost identical to link syntax — just add an exclamation mark ! before the square brackets. Once you have mastered links above, images will feel completely natural.

Accessibility note: See our complete Markdown syntax guide for best practices on alt text, image formats, and SEO considerations.

Basic Image Syntax

![MarkdownMaster Logo](/og-image.svg "MarkdownMaster - Free Online Editor")

The parts:

• ! — tells Markdown this is an image (not a link)
• [alt text] — alternative text displayed when the image cannot load (important for accessibility and SEO)
(url "optional title") — the image URL and an optional hover title

SEO tip: Always write descriptive alt text. Search engines use it to understand image content, and screen readers rely on it for accessibility. A good alt text describes what the image shows, not what it is — write "Chart showing user growth from 100 to 5,000" not "image of chart".

Image Sizing

Standard Markdown does not support image resizing. To control the size, use an HTML <img> tag:

This is widely supported in GitHub Flavored Markdown and most modern renderers.

Clickable Images

To make an image link to another page, wrap the image syntax in a link:

[![MarkdownMaster](/og-image.svg)](https://markdownmaster.site/editor/)

The entire image becomes a clickable link. This is commonly used for badges, logos, and thumbnail galleries.

Advanced Techniques

Footnotes

Footnotes let you add supplementary information without cluttering the main text. They are supported in GFM and many Markdown extensions. For a broader reference of all Markdown features, see our complete Markdown syntax guide.

Here is a statement.[^1]

[^1]: This is the footnote content.

Rendered output will show a superscript number in the text ([^1] becomes a clickable ¹) and a numbered footnote section at the bottom of the document.

Relative Links

In project documentation (README files, wikis, etc.), you often link to other files in the same repository. Use relative paths:

[Contributing Guide](./CONTRIBUTING.md)
[API Docs](/docs/api.md)
[Parent Directory](../README.md)

On GitHub, these links work both in the rendered Markdown and in the repository file browser.

Common Pitfalls

1. Spaces in URLs

If your URL contains spaces, you must encode them as %20 or the link will break:

| Wrong | [My Page](https://example.com/my page) |
| Right | [My Page](https://example.com/my%20page) |

2. Missing Alt Text

Leaving the alt text empty (![](url)) works technically but hurts accessibility and SEO. Always include descriptive alt text.

3. Parentheses in Link Text

If your link URL itself contains parentheses (common in Wikipedia links), use URL-encoded %29 for closing parentheses, or use reference-style links to avoid the ambiguity.

4. Image Paths in Static Sites

In static site generators (like Astro, Hugo, or Jekyll), image paths are relative to the output directory, not the source file. Always test your image paths after building.

FAQ

Can I use Markdown links inside table cells?

Yes. Inline links work perfectly inside table cells. Reference-style links also work, but the reference definition must be somewhere in the same document.

How do I open a link in a new tab?

Standard Markdown does not support the target="_blank" attribute. You need to use raw HTML: <a href="url" target="_blank">text</a>

Can I embed videos in Markdown?

Standard Markdown does not support video embedding. Some platforms (like GitHub) support embedding via raw HTML <video> tags or by pasting a YouTube link on its own line. Check your specific platform's documentation.

What is the difference between ! and no ! before brackets?

The ! prefix distinguishes images from links. [text](url) creates a clickable link. ![alt](url) displays an image. This is the only difference in syntax between the two.

Practice right now in our free Markdown editor — paste any of the examples above and see the live preview instantly.