Reference · Intermediate
The link element
Use link in document metadata to connect stylesheets, canonical URLs, icons, manifests, feeds, and performance hints to the current page.
- Published
- Last checked
Definition
link describes a relationship between the current document and another
resource. It normally belongs in the document head. The rel value determines
whether the browser fetches a stylesheet, records canonical identity, discovers
a feed or icon, or applies a resource hint.
Common relationships
<link rel="stylesheet" href="/assets/site.css" />
<link rel="canonical" href="https://example.com/current-page" />
<link rel="alternate" type="application/atom+xml" href="/feed.xml" />Each relationship has its own attribute rules. A canonical is a hint about URL identity; it does not redirect users or override contradictory server behavior.
Loading and performance
Stylesheets can block rendering because the browser needs their rules before painting. Preload and preconnect can help only when they identify genuinely early, high-value work. Excessive hints compete with necessary requests and can make performance worse. Measure the production waterfall before adding them.
Browser and accessibility behavior
The element has no ordinary visible box and is not a navigation link for users.
Use a for a clickable destination in page content. Some relationships affect
browser UI or discovery, but they do not replace visible navigation, meaningful
titles, or server headers.
Common failures
- A relative canonical resolves to the Preview hostname in production.
- A stylesheet URL redirects or returns HTML with the wrong content type.
- Preload downloads a resource that is never used or is fetched again under different credentials.
- An icon or manifest path works only from the home route.
Verification checklist
Inspect the rendered production head, not only the source template. Request each linked resource and verify status, content type, cache headers, CORS behavior, and final URL. Compare the canonical with the public redirect policy and sitemap. Use the network panel to confirm resource hints prevent real delay rather than adding duplicate work.
Repeat the inspection under the canonical Production hostname. Preview builds can resolve relative URLs and environment-dependent metadata differently. A correct local head is only source evidence; the served response is the public contract browsers and crawlers receive.