Markdown Links and Images — Syntax, Reference-Style, and Tips

Markdown links and images share the same syntax — images just add a ! prefix. Getting them right is essential for READMEs, documentation, and blog posts.

Use the Markdown Preview to preview links and images as you write.

Inline links

[link text](https://example.com)
[Visit the docs](https://docs.example.com/guide)

Renders as: Visit the docs

Links with titles

[link text](https://example.com "This title appears on hover")
[View source](https://github.com/example/repo "GitHub repository")

The title appears in the title attribute of the <a> tag.

Links to headings (anchors)

Link to a heading within the same document:

See the [Installation section](#installation) for setup instructions.
See [Configuration Options](#configuration-options).

GitHub auto-generates anchor IDs from heading text: lowercase, spaces become hyphens, special characters removed.

Relative links

For documentation sites and READMEs:

[Contributing guide](./CONTRIBUTING.md)
[API reference](../docs/api.md)
[Configuration](./docs/config.md#options)

Reference-style links

For readability when you use the same URL multiple times:

Check the [documentation][docs] and [changelog][changelog].

Later in the document:

[docs]: https://docs.example.com
[changelog]: https://github.com/example/repo/CHANGELOG.md

Case-insensitive, can use any ID:

[Visit Google][google-link]
[Search with Google][google-link]

[google-link]: https://www.google.com

Numbered reference-style:

[First reference][1]
[Second reference][2]

[1]: https://example.com
[2]: https://other.com

Autolinks

URLs and email addresses are auto-linked in most Markdown renderers:

https://example.com
user@example.com

For explicit autolinks with angle brackets:

<https://example.com>
<user@example.com>

Images

Images are identical to links but prefixed with !:

![alt text](image.jpg)
![Profile photo](https://example.com/avatar.png)
![Logo](./assets/logo.svg "Company Logo")

• ! — triggers image rendering
• alt text — describes the image (for accessibility and when image fails to load)
• image.jpg — URL or relative path
• "title" — optional hover title

Images in READMEs

![Build Status](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)
![npm version](https://img.shields.io/npm/v/package-name.svg)
![License](https://img.shields.io/badge/license-MIT-blue.svg)

Reference-style images

![Main screenshot][screenshot]
![Mobile view][mobile]

[screenshot]: ./docs/images/screenshot.png
[mobile]: ./docs/images/mobile.png

Clickable images (link wrapping image)

[![Build Status](https://ci.example.com/badge.svg)](https://ci.example.com/builds)

Wraps the image in a link — clicking the image navigates to the URL.

Image sizing

Standard Markdown has no image sizing syntax. Options:

<!-- HTML (works in most renderers): -->
<img src="screenshot.png" alt="Screenshot" width="600">

<!-- GitHub doesn't allow style attributes, but width works: -->
<img src="screenshot.png" alt="Screenshot" width="50%">

In documentation tools like Docusaurus or VitePress, you may have format-specific sizing:

![Screenshot](./screenshot.png =600x400)   <!-- Some renderers -->
![Screenshot](./screenshot.png){width=600} <!-- Pandoc -->

Alt text best practices

<!-- BAD: non-descriptive -->
![image](photo.jpg)
![](photo.jpg)

<!-- GOOD: describes the content -->
![Dashboard showing monthly revenue graph with upward trend](dashboard.png)
![Screenshot of the login form with email and password fields](login.png)

<!-- For decorative images (empty alt): -->
<img src="divider.svg" alt="">

Good alt text helps screen readers, shows when images fail to load, and is used by search engines.

Relative paths in different contexts

Repository structure:
docs/
  guide.md
  images/
    screenshot.png
README.md

In README.md:

![Screenshot](./docs/images/screenshot.png)

In docs/guide.md:

![Screenshot](./images/screenshot.png)

Related tools

• Markdown Preview — preview Markdown rendering
• Markdown Cheatsheet — complete syntax reference
• GitHub Markdown Guide — GitHub-specific features