The HTML Link Element

Your web page is rarely alone. It needs a stylesheet to look good, an icon for the tab, maybe a translated version, a web app manifest, and a canonical address to tell search engines which copy is the real one. How does the page say all this to the browser?

With the <link> element. It describes a relationship between your page and another file or address. Think of it as a signpost in the head: it does not appear on the page, but it tells browsers and search engines where related things live.

What You Will Learn

What <link> is, and how it differs from <a>
The rel attribute: the heart of every link tag
Linking stylesheets, with media conditions
Canonical addresses and translated versions (hreflang)
Performance hints: preload, preconnect, dns-prefetch, prefetch
Security attributes: integrity, crossorigin, and referrerpolicy

The Big Idea

index.html
<head>
  <meta charset="utf-8">
  <title>Sourdough for Beginners</title>

  <link rel="stylesheet" href="/css/site.css">
  <link rel="icon" href="/favicon.svg" type="image/svg+xml">
  <link rel="canonical" href="https://example.com/sourdough">
  <link rel="alternate" hreflang="hi" href="https://example.com/hi/sourdough">
  <link rel="manifest" href="/site.webmanifest">
  <link rel="preconnect" href="https://fonts.example.com">
</head>

Try each combination: remove the link, or limit it to print only, or to narrow screens. The browser reads the same tag, and decides whether the styles apply.

`<link>` Is Not `<a>`

They share a word, but have different jobs:

	`<link>`	`<a>`
Where	In the head	In the body
Visible?	No	Yes, and clickable
Purpose	Describes a relationship for the browser	Lets a visitor travel to another page
Content	None (a void element, with no closing tag)	Link text

If you want a clickable link, use <a href="…">. A <link> in the head will never be clickable.

The Most Important Attribute: `rel`

rel is short for relationship. It says what kind of thing the linked file is. Without it, a link tag does nothing.

<link rel="stylesheet" href="/css/site.css">

Here, rel="stylesheet" says "this is a stylesheet", and href says where to find it.

`rel` value	Meaning
`stylesheet`	A CSS file to apply to the page
`icon`	The site's small picture (see Favicon)
`apple-touch-icon`	An icon for the home screen of Apple devices
`manifest`	A web app manifest (name, icons, colours for installable apps)
`canonical`	The preferred address for this content
`alternate`	Another version of this page: another language, a feed, a print version
`preload`	Fetch this important file early
`preconnect`	Open a connection to another site early
`dns-prefetch`	Look up another site's address early
`prefetch`	Fetch something that a later page will probably need
`modulepreload`	Fetch a JavaScript module early
`author`, `license`, `help`, `search`	Describe related resources

You can combine values with spaces, such as rel="alternate stylesheet". A typo, such as stylsheet, makes the browser ignore the tag without any error message.

Common Attributes

Attribute	Use
`href`	The address of the linked file
`type`	The file type, such as `image/svg+xml` (helps the browser skip unsupported types)
`media`	A condition for when to use the file, such as `print`
`as`	What a preload is for: `style`, `script`, `font`, `image`
`crossorigin`	How to ask other sites for the file (needed for fonts and for integrity checks)
`integrity`	A fingerprint to verify the file was not changed
`hreflang`	The language of the linked page (used with `alternate`)
`sizes`	Icon sizes, used with `icon`
`referrerpolicy`	How much of your address to send when fetching the file
`fetchpriority`	A hint: `high`, `low`, or `auto`
`disabled`	Stops a stylesheet from being applied (useful with scripts)

Linking Stylesheets

<link rel="stylesheet" href="/css/site.css">

Things to know:

A stylesheet link is render-blocking. The browser waits for it before showing the page, so that you do not see an unstyled flash. That is good, but it also means a huge or slow stylesheet delays everything. Keep CSS small.
You can link several stylesheets. They apply in order, so later rules can override earlier ones.
If the file cannot be loaded, the page still shows, only without those styles.
Do not use @import inside CSS for important files. It makes the browser discover files one after another. Use separate <link> tags instead.

The `media` Attribute

media makes a stylesheet apply only when a condition is true:

<link rel="stylesheet" href="/css/base.css">
<link rel="stylesheet" href="/css/print.css" media="print">
<link rel="stylesheet" href="/css/wide.css" media="(min-width: 900px)">
<link rel="stylesheet" href="/css/dark.css" media="(prefers-color-scheme: dark)">

The browser still downloads these files (usually at lower priority), but only applies them when the condition matches. A stylesheet whose condition does not match does not block the first display of the page.

Try It: Check Your Link Tags

The checker below reads your link tags with the browser's real parser, and points out the usual problems: missing href, a misspelt rel, a preload without as, a font without crossorigin, and a relative canonical.

links.html
<!-- Good: complete and correct -->
<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>
<link rel="canonical" href="https://example.com/sourdough">
<link rel="stylesheet" href="https://cdn.example.com/lib.css"
      integrity="sha384-…" crossorigin="anonymous">

Canonical Addresses

The same page can often be reached by several addresses:

https://example.com/sourdough
https://example.com/sourdough?utm_source=newsletter
https://www.example.com/sourdough/

Search engines may treat these as separate pages, and split their attention between them. A canonical link names the preferred one:

<link rel="canonical" href="https://example.com/sourdough">

Use a full address, and point to a page that really exists. It is a strong hint, not a command. Search engines may choose differently.

Translated Versions: `hreflang`

If your page exists in several languages, tell search engines about each:

<link rel="alternate" hreflang="en" href="https://example.com/en/sourdough">
<link rel="alternate" hreflang="hi" href="https://example.com/hi/sourdough">
<link rel="alternate" hreflang="x-default" href="https://example.com/sourdough">

Rules:

Each version lists all versions, including itself. The links must be reciprocal, or they may be ignored.
Use full addresses.
x-default names the page to use when no language matches.
Use correct language codes, such as pt-BR.

Use the builder to create a set, and then paste it into each version of the page:

hreflang.html
<link rel="alternate" hreflang="en" href="https://example.com/en/sourdough">
<link rel="alternate" hreflang="es" href="https://example.com/es/sourdough">
<link rel="alternate" hreflang="x-default" href="https://example.com/sourdough">

Performance Hints

These tell the browser what to do early. They are powerful, but each one has a cost, so use them carefully.

`preload`: "You will definitely need this soon"

<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>

Use it for a few critical files the browser would otherwise find late, such as the main font, or an image at the top of the page.
as is required, so the browser can choose the right priority and settings.
Fonts need crossorigin, even from your own site.
If the file is not used soon after, the browser may warn in the console. Preloading too much slows down the files that matter.

`preconnect`: "Get ready to talk to this site"

<link rel="preconnect" href="https://fonts.example.com" crossorigin>

It opens the connection early (address lookup, secure handshake), so the first request is faster. Use it for one to three other sites that you are sure to use immediately. More than that wastes effort.

`dns-prefetch` and `prefetch`

<link rel="dns-prefetch" href="https://analytics.example.com">
<link rel="prefetch" href="/next-page.html">

dns-prefetch only looks up the address. It is cheap, and a fallback for older browsers.
prefetch downloads a file that the next page will probably need, at low priority. Do not use it on slow or limited connections.

Measure before you hint

Performance hints help only when they solve a real delay. Test your page with the browser's developer tools and a speed testing tool before and after, and keep a hint only if it helps.

Links in Docusaurus

In a Docusaurus site, you rarely write these by hand. The config file has settings for favicon, stylesheets, and headTags, and Docusaurus adds the canonical link and the language alternates when you turn on internationalisation. You can add one yourself in a component with @docusaurus/Head. Check the built page's source to see what was produced.

Good Habits

Always set rel and href.
Use full addresses for canonical and hreflang.
Keep stylesheets small, and avoid @import.
Use media for print, wide, and dark-mode styles.
Preload only a few critical files, with as and crossorigin where needed.
Limit preconnect to a few important sites.
Add integrity and crossorigin for files from other sites.
Make hreflang links reciprocal, including x-default.
Spell-check rel values.
Measure the effect of any hint you add.

Accessibility Checklist

The stylesheet that provides focus outlines, contrast, and readable text loads reliably.
A stylesheet failing to load still leaves the page readable and usable.
A print stylesheet keeps text readable on paper, and shows link addresses if they matter.
Dark and high-contrast styles keep sufficient contrast.
Translated versions are connected with hreflang and use the matching lang.
Feeds have a clear title, so people can tell them apart.
Heavy preloading does not slow down the page for people on weak devices.

Security and Privacy Notes

A stylesheet from another site has power over your page. It can hide, move, or redraw content, and some attacks use CSS to leak data. Link only to sources you trust.
Use Subresource Integrity with integrity and crossorigin="anonymous", to detect changed files. See Third-Party Content Security.
preconnect, prefetch, and dns-prefetch contact other sites before the visitor clicks anything. That can reveal that someone visited your page, to the other site. Do not use them for sites you would not want to be linked to.
Fonts and styles from public services may log visitors' addresses. Some privacy laws treat that as personal data, so consider hosting files yourself. This is not legal advice.
Use referrerpolicy to limit what your address reveals when fetching a file.
Never put private addresses in link tags. They are public.
Escape dynamic values. If a server writes href from user input, a malicious value can load an attacker's file.

Global Audience Notes

Use hreflang so people find the version in their language, and offer a visible language switcher too.
Do not auto-redirect by country. Use the links and let visitors choose.
Prefetching wastes data for people who pay by the megabyte. Respect data-saver settings, and use prefetch sparingly.
Hosting files yourself, or from a nearby network, helps visitors in regions where far-away servers are slow, or where some services are blocked.
Fonts for other scripts can be large. Load only the scripts you need, and keep a fallback font.
Print stylesheets and paper sizes differ by region (A4 or Letter), so test both.

Common Mistakes to Avoid

No rel or a misspelt rel.
No href.
Using <link> when you want a clickable link.
A relative canonical address.
A preload without as.
A font preload without crossorigin.
Preloading or preconnecting too many files.
hreflang that is not reciprocal.
@import chains instead of separate links.
A huge render-blocking stylesheet.
A third-party stylesheet with no integrity check.
Linking over plain http.

Practice Time

Try these in your editor:

Link a stylesheet, then misspell rel, and see what happens.
Add a print.css with media="print", and use your browser's print preview.
Add a stylesheet that applies only at (min-width: 900px).
Add a dark-mode stylesheet, and switch your system theme.
Add a canonical link to a page with a query string in its address.
Create hreflang links for two languages, with x-default.
Preload a font, and look in the Network panel for when it starts.
Add a preconnect, and compare the timing with and without it.
Add a manifest link, and check the Application panel in developer tools.
Bonus: paste your live site's link tags into the checker, and fix what it finds.

Quick Recap

Click a question to check your answer.

1. What does the link element do?

It describes a relationship between the page and another resource, such as a stylesheet, an icon, a translation, or a preferred address. It lives in the head and is not visible.

2. What is the difference between link and a?

link is in the head, is invisible, and describes a relationship for the browser. a is in the body, is visible, and lets the visitor click to travel.

3. What does the media attribute do on a stylesheet link?

It limits when the stylesheet applies, for example only for print, or only on wide screens, or only in dark mode.

4. What are the rules for hreflang?

Use full addresses, include every language version and the page itself on each version, add x-default, and make the links reciprocal.

5. What does preload need to work properly?

An as attribute that says what kind of file it is, and crossorigin for fonts. Use it for only a few critical files.

6. Why add integrity to a link to another site's file?

It lets the browser check that the file has not been changed, and refuse it if it has. It needs crossorigin for files from other sites.

Key Takeaways

<link> is an invisible signpost in the head. rel says what the relationship is.
Use it for stylesheets, icons, manifests, canonical addresses, translations, and feeds.
media applies a stylesheet only when a condition matches.
A canonical link and hreflang links need full addresses, and hreflang must be reciprocal.
preload, preconnect, and friends speed up key files, but too many slow things down.
Files from other sites need trust, integrity, and crossorigin.
Contacting other sites early can reveal visits, so choose them with care.

Next, give your site its little face with the Favicon.

What You Will Learn​

The Big Idea​

<link> Is Not <a>​

The Most Important Attribute: rel​

Common Attributes​

Linking Stylesheets​

The media Attribute​

Try It: Check Your Link Tags​

Canonical Addresses​

Translated Versions: hreflang​

Performance Hints​

preload: "You will definitely need this soon"​

preconnect: "Get ready to talk to this site"​

dns-prefetch and prefetch​

Other Useful Link Tags​

Links in Docusaurus​

Good Habits​

Accessibility Checklist​

Security and Privacy Notes​

Global Audience Notes​

Common Mistakes to Avoid​

Practice Time​

Quick Recap​

Key Takeaways​