Links & Images

~12 min · markdown, links, images, accessibility

Level 0Plaintext

0 XP0/64 lessons0/12 achievements

0/100 XP to next level100 XP to go0% complete

Inline, reference, and autolinks

Markdown links come in three styles. Inline ([text](url)) is the default — fine for short documents. Reference ([text][id] with [id]: url elsewhere) keeps prose readable when you have many links. Autolinks (<https://example.com>) wrap raw URLs.

Images use the same syntax with a leading bang

![alt text](url). The alt text is not optional — screen readers depend on it, and it shows when the image fails to load. Empty alt (![](url)) explicitly signals 'decorative'.

Sizing requires HTML

CommonMark has no syntax for image dimensions. When you need control, drop down to an <img> tag with width, height, or style attributes. Most Markdown renderers allow inline HTML.

Accessibility principle: alt text describes the image's function in context, not its appearance. A logo at the top of a doc has alt='Acme Corp logo', not alt='Three blue triangles'.

Code

Inline links·markdown

[Link text](https://example.com)
[With title](https://example.com "Hover title")

Reference-style (prose stays readable)·markdown

Read the [CommonMark spec][cm] for details.
Also see [GFM][].

[cm]: https://commonmark.org "CommonMark"
[GFM]: https://github.github.com/gfm/

Autolinks·markdown

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

Images + sizing fallback·markdown

![Alt text](https://example.com/image.png)
![Logo](./logo.png "Optional title")

<!-- Need a width? Drop to HTML: -->
<img src="photo.png" alt="Description" width="400">

External links

Exercise

Convert one of your existing READMEs to use reference-style links instead of inline. Notice how the prose reads more like prose and less like a dictionary of URLs. Decide for yourself when each style fits.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousLists — Unordered, Ordered, Nested, Tasks Next →Code — Inline & Fenced Blocks

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.