Links and Images

Reviewed & published by Brayan K

By the end of this lesson you'll be able to add clickable links, hover tooltips, reusable reference links, autolinks, and embedded (or clickable) images to any Markdown document — and you'll be able to picture the rendered result before you ever open a previewer.

Part of the free Markdown course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

What You'll Learn

• Write inline links with [text](url) and read the rendered result
• Add a hover tooltip with [text](url "title")
• Reuse one URL many times with reference-style links [text][ref]
• Make bare URLs clickable with autolinks <https://...>
• Embed images with  and write good alt text
• Create clickable images and use relative paths inside a repo

💡 Real-World Analogy

A link is a signpost. The words in [square brackets] are what the signpost says — the part readers see and click. The (parentheses) are the direction it points — the URL nobody reads but everybody follows. An image is the exact same signpost with a single ! stamped in front, which tells Markdown: "don't make a clickable label here — actually show the thing at this address." Remember the order — label first [], address second () — and you've learned 90% of this lesson.

1. Inline Links

An inline link puts the destination right next to the text. The shape is always [text](url) with no space between the ] and the (. The text in brackets is what your reader sees and clicks; the URL in parentheses is where they go.

Source → Rendered

Read the [official docs](https://developer.mozilla.org) today.

Only the bracketed words become the link — the URL itself is hidden from the reader.

2. Links With a Title (Tooltip)

Add a quoted string after the URL, still inside the parentheses, to give the link a title — the little tooltip that pops up on hover. The shape is [text](url "title"). Mind the space before the quote and that the quotes stay inside the ().

[MDN Docs](https://developer.mozilla.org "Mozilla Developer Network")

RENDERED RESULT (hover over the link)

Hover the link above — your browser shows the title "Mozilla Developer Network".

3. Reference-Style Links

When the same URL appears many times — or you just want your prose to stay readable — use a reference-style link. You write a short label where the link appears, then define that label once anywhere in the document. The shape is [text][label] plus a separate [label]: url line. The definition line never shows up in the rendered output.

Read the [install guide][setup], then the [API docs][api].

[setup]: https://docs.example.com/install
[api]: https://docs.example.com/api "API Reference"

The two [label]: url lines vanish from the output — they only tell Markdown where each label points. Labels are case-insensitive and can be reused as many times as you like.

4. Autolinks

If you just want a raw URL to become clickable with no separate label, wrap it in angle brackets: <https://...>. The URL becomes both the link text and the destination. This also works for email addresses, e.g. <[email protected]>.

Status page: <https://status.example.com>
Contact: <[email protected]>

Without the angle brackets, many parsers leave a bare URL as plain, unclickable text.

Here's all four link styles in one runnable example. Read every comment, run it, and confirm the printed Markdown matches what you expect.

## Inline link
[Visit Google](https://google.com)
## Inline link WITH a title (hover tooltip)
[MDN Docs](https://developer.mozilla.org "Mozilla Developer Network")
## Autolink
<https://example.com>
## Reference-style link
Read the [install guide][setup] before you start.
[setup]: https://docs.example.com/install

<!-- ✅ Expected result, rendered:
     h2 -> text: Inline link
     h2 -> count: 4
     p  -> count: 4
     a  -> count: 4
-->

Your turn. The program below is almost complete — fill in the three ___ blanks using the 👉 hints, then run it and check the printed lines against the expected output in the comments.

// 🎯 YOUR TURN — replace each ___ then press "Try it Yourself".
// These lines PRINT Markdown. Fix them so the printed text is valid Markdown.

// 1) Make an INLINE link: the words "My Portfolio" pointing to https://me.dev
console.log("[My Portfolio]___");        // 👉 replace ___ with (https://me.dev)

// 2) Add a TITLE tooltip "Source code" to a GitHub link:
console.log('[Repo](https://github.com/me/app ___)'); // 👉 replace ___ with "Source code"

// 3) Turn this bare URL into an AUTOLINK — wrap it in angle brackets:
console.log("___");   // 👉 replace ___ with <https://example.com>

// ✅ Expected printed output:
// [My Portfolio](https://me.dev)
// [Repo](https://github.com/me/app "Source code")
// <https://example.com>

5. Images

An image is a link with one extra character: a leading !. The shape is . The alt text in the brackets is not a label this time — it's the description screen readers announce and the text that shows if the image fails to load. Always write meaningful alt text. You can add a title tooltip exactly like a link: .

![A golden retriever puppy](puppy.jpg "So cute")

The framed box stands in for the real picture. If the file at puppy.jpg can't load, that alt text — "A golden retriever puppy" — is exactly what readers (and screen readers) get instead.

6. Clickable (Linked) Images

To make an image clickable, put the whole image syntax inside a link's brackets: [](destination). The image is the "text" of the link. This is how README badges work — a status badge image that links to your build pipeline.

[![Build passing](build-badge.svg)](https://ci.example.com)

RENDERED RESULT (the whole image is a link)

Notice the nesting order: the ![...] image sits in the spot where a link's text would normally go.

7. Relative Links & Paths

URLs starting with https:// are absolute. But inside a project you usually point to files that live alongside your Markdown — that's a relative path, with no https://. ./docs/setup.md means "the setup file in the docs folder next to me"; images/banner.png works the same way for images. Relative paths keep working when you move the whole repo, which is why GitHub READMEs use them.

See the [contributing guide](./CONTRIBUTING.md).

![Project banner](images/banner.png)

Relative links resolve against the file's own location, so the same Markdown works on your machine, on GitHub, and on a docs site.

Here are all the image patterns in one runnable example — basic, titled, clickable, reference-style, and relative.

## Basic image
![A golden retriever puppy](https://placedog.net/300/200)
## Image with a title
![Company logo](./logo.png "Acme Inc.")
## Linked (clickable) image
[![App screenshot](./shot.png)](https://myapp.com)
## Reference-style image
![Architecture diagram][arch]
[arch]: ./docs/architecture.svg
## Relative path (same repo)
![Banner](images/banner.png)

<!-- ✅ Expected result, rendered:
     h2  -> text: Basic image
     h2  -> count: 5
     p   -> count: 5
     a   -> count: 1
     img -> count: 4
-->

Your turn again. Fill in the three ___ blanks below — one of them is just adding the missing ! — then run it and check against the expected output.

// 🎯 YOUR TURN — replace each ___ then press "Try it Yourself".

// 1) EMBED an image of a cat. alt text = "Sleepy cat", url = cat.jpg
console.log("___[Sleepy cat](cat.jpg)");   // 👉 a link becomes an image by adding ___

// 2) Make a CLICKABLE image: wrap an image of logo.png in a link to https://acme.dev
console.log("[![Acme](logo.png)]___");      // 👉 replace ___ with (https://acme.dev)

// 3) RELATIVE path: embed assets/hero.png with alt text "Hero banner"
console.log("![Hero banner]___");           // 👉 replace ___ with (assets/hero.png)

// ✅ Expected printed output:
//    ![Sleepy cat](cat.jpg)
//    [![Acme](logo.png)](https://acme.dev)
//    ![Hero banner](assets/hero.png)

Pro Tips

• 💡 Standard Markdown can't resize images. Drop down to HTML when you need a width: <img src="logo.png" width="200" alt="Logo"> works right inside Markdown.
• 💡 Encode spaces in URLs. A space breaks the link; write %20 instead — (my%20file.pdf), not (my file.pdf).
• 💡 Reference links keep prose readable. If a paragraph has five links, reference style stops the raw URLs from drowning the sentence.
• 💡 Badges are clickable images. Generate them at shields.io and wrap them in a link to the thing they report on.

Common Errors (and the fix)

• Brackets and parentheses swapped: (text)[url] renders as literal text, not a link. The label always comes first in [ ], the URL second in ( ) — [text](url).
• Forgot the ! on an image: [alt](photo.png) makes a link to the file;  shows the image. The bang is what turns a link into an image.
• Reference label never defined: [text][docs] with no matching [docs]: url line renders as plain bracketed text. Check the label spelling — it's case-insensitive but must match.
• A space inside the URL: [file](my report.pdf) breaks at the space. Encode it: [file](my%20report.pdf), or rename the file to avoid spaces.
• A space between ] and (: [text] (url) won't link. Keep them touching: [text](url).

📋 Quick Reference

Frequently Asked Questions

Q: What's the real difference between an inline and a reference-style link?

Only where the URL lives. Inline keeps the URL right beside the text; reference style moves it to a separate [label]: url line so your paragraph stays clean. They render identically.

Q: Why won't my image show up — I only see the alt text?

The URL or path is wrong, so the file can't load and the alt text is the fallback. Check for a missing !, a typo in the path, or a relative path pointing at the wrong folder.

Q: Can I resize or centre an image in Markdown?

Not with plain Markdown. Use HTML, which most renderers accept: <img src="x.png" width="300">, and wrap it in <p align="center">…</p> to centre it.

Q: My link has a space in the URL and breaks — what do I do?

Replace each space with %20 (URL encoding), e.g. (report%20final.pdf). Better yet, avoid spaces in filenames altogether.

Mini-Challenge: a README Footer

No blanks this time — just a brief and an outline. Write the console.log calls that print valid Markdown for an inline link, a reference-style link, and a clickable badge image. Run it and compare against the expected output in the comments.

// 🎯 MINI-CHALLENGE: a tiny README footer
// Use console.log to PRINT valid Markdown for ALL of the following:
// 1. An inline link: the word "Docs" -> https://docs.acme.dev
// 2. A reference-style link: "Report a bug" using the label [bugs],
//    then define  [bugs]: https://github.com/acme/app/issues
// 3. A clickable badge image: the image
//    https://img.shields.io/badge/build-passing-green  linked to
//    https://github.com/acme/app/actions
//
// ✅ Expected printed output (order doesn't matter):
//    [Docs](https://docs.acme.dev)
//    Found a problem? [Report a bug][bugs]
//    [bugs]: https://github.com/acme/app/issues
//    [![build passing](https://img.shields.io/badge/build-passing-green)](https://github.com/acme/app/actions)

// your code here

🎉 Lesson Complete!

• ✅ Inline links: [text](url) — label in [], address in ()
• ✅ Add a tooltip with [text](url "title")
• ✅ Reuse URLs with reference links [text][ref] + [ref]: url
• ✅ Make bare URLs clickable with autolinks <https://...>
• ✅ Images are links with a leading !:  — always write alt text
• ✅ Clickable images [](url) and relative paths like ./docs/file.md

Practice quiz

Continue this course

• Previous: Lists and Tables
• Next: Advanced Markdown Features — Code blocks with syntax highlighting, task lists, footnotes, and GitHub-flavoured Markdown
• Quick reference: Markdown cheat sheet › Links & Media