SEO

Canonical URLs Explained (With Examples)

By REM Web Development4 min read

This tutorial is part of the SEO series for web developers. It assumes you already know the basics from the web programming course.

Here is a question that sounds silly until it costs you traffic: how many addresses does your home page have? Most people answer "one". Search engines usually see more like four or five: 

http://example.com/
http://www.example.com/
https://example.com/
https://www.example.com/
https://www.example.com/index.html

To you these are the same page. To a crawler they are five URLs that happen to return the same HTML. When that happens the search engine has to guess which one is the "real" page, and any links pointing at the other four get split between them instead of adding up. A canonical URL is how you remove the guesswork.

What is a canonical URL?

The canonical URL is the one address you want search engines to index and show in results for a piece of content. You declare it with a link element in the head of the page: 

<head>
    <title>The CSS Box Model</title>
    <link rel="canonical" href="https://www.remwebdevelopment.com/blog/css/css-box-model.html">
</head>

Every version of that page, with or without www, with tracking parameters like ?utm_source=newsletter, or reached through an old URL, should carry the same canonical tag pointing at the same address. That tells the crawler: "whatever URL you used to get here, credit this one."

Rules that actually matter

  • Use absolute URLs. Write the full https://www.… address, not /blog/page.html. Relative canonicals work in theory, but they are an easy place to make a mistake.
  • Self-reference. Every indexable page should have a canonical that points to itself. It costs nothing and protects you against parameters and copies you didn't plan for.
  • One per page. Two canonical tags that disagree are treated as no canonical at all. Watch out for plugins and themes that each add their own.
  • Point at a page that returns 200. A canonical that points to a redirect or a 404 is a contradiction, and search engines will usually ignore it.
  • Keep it consistent with everything else. Your sitemap, internal links, Open Graph og:url and redirects should all use the same version of the URL.

Canonical tag or redirect?

They solve related problems, so people mix them up. The difference is simple:

  • A 301 redirect sends the visitor (and the crawler) to a different URL. Use it when the old address should no longer be visited at all, for example http → https, non-www → www, or a page that moved.
  • A canonical tag leaves the visitor where they are and only tells search engines which version to index. Use it when several URLs legitimately need to work, such as sorted or filtered product lists, print versions, or pages reached with tracking parameters.

Most sites need both: redirects to collapse the protocol and host variations into one, and a self-referencing canonical on every page for whatever is left. We cover the redirect side in 301 Redirects with .htaccess (Without Redirect Chains).

Generating the canonical automatically

Typing canonical tags by hand does not scale, and a typo in one is worse than having none. Generate it from the page's own path in your template instead. In plain JavaScript on the server (or in a static site generator) it looks like this: 

const SITE = 'https://www.remwebdevelopment.com';

function canonicalFor(pathname) {
    // drop query strings and fragments, keep the path exactly as published
    const clean = pathname.split(/[?#]/)[0];
    return new URL(clean, SITE).toString();
}

canonicalFor('/blog/css/css-box-model.html?utm_source=x');
// "https://www.remwebdevelopment.com/blog/css/css-box-model.html"

This site is built with Astro, and the layout does exactly that: new URL(Astro.url.pathname, site.url). Every page gets a correct, absolute, self-referencing canonical without anyone having to remember it.

How to check your canonicals

  1. Open the page, view source, and search for rel="canonical". There should be exactly one.
  2. Copy its href into the address bar. It should load directly with status 200, not redirect.
  3. In Google Search Console, the URL Inspection tool shows both the "User-declared canonical" and the "Google-selected canonical". If they differ, Google disagrees with you, which usually means your internal links or sitemap point somewhere else.
<!-- quick check from the command line -->
curl -s https://www.example.com/some-page.html | grep -i 'rel="canonical"'

Common mistakes

  • Every page's canonical points at the home page. This happens when a theme hard-codes it, and it tells search engines your whole site is one page.
  • Paginated lists (page 2, 3, …) canonical to page 1, so the articles linked from later pages are harder to discover.
  • The canonical uses http:// while the site redirects to https://.
  • Staging sites get copied to production with the staging domain still in the canonical.

Canonicals are one small part of technical SEO. For the bigger picture of how crawling, indexing and site structure fit together, Southern Whale has a plain-English overview: What Is Technical SEO?