Links and Images

Inline Links

Square brackets for the text, parentheses for the destination.

[link text](https://example.com)
[with a title](https://example.com "Hover tooltip")
[relative path](./docs/guide.md)
[a heading in this file](#installation)
[a heading in another file](./guide.md#installation)
[email](mailto:hi@example.com)
[a URL with spaces](<https://example.com/my page>)

Rules worth knowing:

• The title in quotes becomes the HTML title attribute, shown as a tooltip. Single quotes and parentheses also delimit it.
• A destination containing spaces or parentheses must be wrapped in angle brackets or percent-encoded.
• Link text can contain emphasis and code spans, but not another link.
• There is no way to set target="_blank" in Markdown, that requires raw HTML or a renderer setting.

[**bold** and `code` in link text](https://example.com)
[not allowed](https://a.com) inside [another](https://b.com)

Reference Links

The destination is defined once, elsewhere in the document, and referenced by label. Useful when the same URL appears repeatedly, or when a long URL would wreck the line.

See the [docs][docs] and the [API reference][api].
The [changelog] uses a shortcut reference.

[docs]: https://example.com/docs
[api]: https://example.com/api "API reference"
[changelog]: https://example.com/changelog

Definitions can sit anywhere, are not rendered, and can be reused any number of times. Labels are case insensitive and collapse whitespace, so [Docs] and [docs] resolve to the same definition. An undefined label renders as literal brackets, which is the usual cause of stray [text][label] in published docs.

Autolinks and Bare URLs

CommonMark autolinks require angle brackets. GFM adds automatic detection of bare URLs.

<https://example.com>          CommonMark, becomes a link
<hi@example.com>               CommonMark, becomes a mailto link
https://example.com            GFM only, bare URL becomes a link
www.example.com                GFM only, gets an implicit http scheme
hi@example.com                 GFM only, becomes a mailto link

A bare URL in strict CommonMark stays plain text, so the angle-bracket form is the portable one. GFM's autolinking is also why a URL you did not want linked (in an example, say) needs a code span:

Do not link this: `https://example.com`

GFM trims trailing punctuation from an autolink, so a URL ending a sentence keeps the period out of the href, but a trailing ) still frequently breaks the detection.

Relative and Anchor Links

Relative links resolve against the file's location in the rendered site or repository, so they are how you cross-link docs without hardcoding a domain.

[same directory](./setup.md)
[parent directory](../README.md)
[from the repo root](/docs/setup.md)
[a directory](./docs/)
[an image in the repo](./assets/diagram.png)

On GitHub, a root-relative link like /docs/setup.md resolves to the repository root on the current branch, which is why it survives branch switches while a full https://github.com/... URL pins to one branch.

Anchor links target a heading's generated id. GitHub derives it by lowercasing, stripping punctuation, and replacing spaces with hyphens.

markdown

Getting Started -> #getting-started

API: v2 notes -> #api-v2-notes

What's new? -> #whats-new

markdown jump jump to a duplicate heading jump in another file

Because slugging is not standardized, an anchor that works on GitHub can 404 in a static-site generator that slugs differently. Verify anchors after changing renderers.

Images

An image is a link with a leading !. The bracketed text is the alt text, not a caption.

![alt text](./diagram.png)
![alt text](./diagram.png "Optional title")
![](./decorative.png)
![alt text][img-ref]

[img-ref]: https://example.com/diagram.png

• Alt text is for screen readers and for when the image fails to load. Describe the content, do not write "image of".
• An empty alt is correct for a purely decorative image.
• Markdown has no caption syntax. A caption is either a paragraph below the image or raw HTML <figure>.
• Markdown has no width, height, or alignment syntax either.

A linked image nests an image inside a link, and the order matters: the image goes inside the square brackets.

[![build status](./badge.svg)](https://ci.example.com/build)
[![alt](./thumb.png)](./full-size.png)

That pattern is what every README badge is.

Sizing and Alignment on GitHub

Since Markdown itself has no sizing syntax, GitHub supports two extensions.

![alt](./diagram.png#gh-dark-mode-only)
![alt](./diagram-light.png#gh-light-mode-only)

For dimensions, GitHub allows a raw <img> tag with width and height, and accepts pixels or a percentage.

<img src="./diagram.png" alt="architecture" width="400">
<img src="./logo.png" alt="logo" width="50%">
<p align="center">
  <img src="./hero.png" alt="hero" width="600">
</p>

Neither is portable. The #gh-*-mode-only fragment is GitHub-specific, and the <img> tag depends on the renderer permitting raw HTML, which many sanitizers and CommonMark-only pipelines do not. For a doc that must render everywhere, ship a correctly sized image instead.

Safe Hrefs and Escaping

Renderers sanitize link destinations, and most strip javascript:, data:, and vbscript: schemes, rendering the link as plain text instead.

[blocked by most renderers](javascript:alert(1))

To write literal brackets, escape them.

\[not a link\]
\!\[not an image\]
This is a literal \[bracketed\] word.

And to show link syntax without it being a link, use a code span.

The syntax is `[text](url)`.