Canonical URLs and Duplicate Content on Static Sites

Static sites are prone to a quiet kind of duplication. Nothing is dynamically generated, yet the same page is often reachable at five or more URLs: with and without a trailing slash, with index.html appended, on www and the apex domain, over HTTP, on a *.pages.dev or *.netlify.app host, and at a pre-migration path someone copied instead of redirecting. Each variant splits links and ranking signals, and search engines sometimes pick a canonical you did not intend — an ugly one, or one on the preview host.

This guide makes every page on a static site answer at exactly one URL and declare it. It covers choosing a trailing-slash policy, redirecting variants at the host, generating self-referencing canonicals from configuration, and a CI check that keeps the three consistent. It is part of Technical SEO for Static Sites. The measurements come from an Eleventy blog of 1,240 posts that had been migrated from Jekyll two years earlier.

Prerequisites

• Access to the host's redirect and header configuration (_redirects, netlify.toml, vercel.json, Workers config, or server config when self-hosting).
• A crawler that reports duplicate content — Screaming Frog, Sitebulb or the free linkinator with a custom script.
• Search Console access to read the page indexing report.

Step 1: Find the Variants

Crawl the live site with the crawler set to follow redirects and report canonicals. Then request the obvious variants of a sample of URLs directly:

for u in \
  https://example.com/posts/css-grid/ \
  https://example.com/posts/css-grid \
  https://example.com/posts/css-grid/index.html \
  https://www.example.com/posts/css-grid/ \
  http://example.com/posts/css-grid/ \
  https://example-blog.pages.dev/posts/css-grid/ ; do
  printf '%-58s ' "$u"; curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' "$u"
done

On the blog, four of the six variants returned 200 with identical content. The host resolved /posts/css-grid to the directory's index.html without redirecting, index.html was served directly, and the pages.dev host was fully public. Screaming Frog found 312 slash/no-slash pairs where both had been linked from somewhere, and Search Console listed 287 URLs as "Duplicate, Google chose different canonical than user".

Step 2: Choose One Trailing-Slash Policy

Pick directory-style URLs with a trailing slash (/posts/css-grid/) or file-style without (/posts/css-grid). Directory style maps naturally onto index.html files and is what Hugo, Eleventy and Astro produce by default. Then make every layer agree:

Internal links must match too. A Markdown link written as [grid](/posts/css-grid) produces a redirect hop on every click and a mixed signal for crawlers. A link checker that treats redirects as warnings, as in Checking Links in Pull Requests, finds them; on the blog it found 1,106 internal links missing the slash.

Step 3: Redirect Variants at the Host

Host and scheme variants are redirected once for the whole zone. On Cloudflare, a single redirect rule sends www to the apex preserving path and query; "Always Use HTTPS" handles the scheme. On Netlify, _redirects handles www when both domains are attached:

# _redirects (Netlify)
https://www.example.com/*   https://example.com/:splat   301!
/*/index.html               /:splat/                     301

Platform hosts such as *.pages.dev or *.netlify.app cannot usually be turned off, but they can be told not to be indexed. Send X-Robots-Tag: noindex for requests whose Host is not the production domain — on Cloudflare Workers, in the Worker; on Netlify, with a _headers rule scoped to the deploy context. robots.txt and noindex for Preview and Staging has complete examples.

Step 4: Emit Canonicals From Configuration

Every indexable page gets <link rel="canonical"> pointing at its own preferred URL, built from the configured production origin — never from the request, never relative:

{# _includes/base.njk #}
{% set canonical = canonicalOverride or (site.url + page.url) %}
<link rel="canonical" href="{{ canonical }}">
<meta property="og:url" content="{{ canonical }}">

site.url comes from a global data file and is always the production origin, so a preview deploy's canonical points at production. canonicalOverride exists for the rare legitimate case — a post syndicated from another site, where the canonical points at the original.

Keep og:url, the sitemap <loc>, JSON-LD mainEntityOfPage and hreflang alternates derived from the same value. When they disagree, search engines have to guess.

Step 5: Check It in CI

A check over the built HTML asserts, for every page: exactly one canonical; it is absolute and on the production origin; it equals the page's own URL (unless the page is in an allowlist of intentional overrides); and og:url equals it. A second check runs the link checker in redirect-as-error mode on internal links.

for (const file of htmlFiles) {
  const html = parse(await readFile(file, 'utf8'));
  const links = html.querySelectorAll('link[rel=canonical]');
  const own = ORIGIN + urlFromFile(file);
  if (links.length !== 1) fail(file, `found ${links.length} canonicals`);
  const href = links[0]?.getAttribute('href');
  if (href !== own && !OVERRIDES.has(own)) fail(file, `canonical ${href} != ${own}`);
  if (html.querySelector('meta[property="og:url"]')?.getAttribute('content') !== href) fail(file, 'og:url mismatch');
}

It found one real regression in its first three months: a layout refactor that rendered two canonicals on paginated archive pages.

Duplicates You Create on Purpose

Not every duplicate is a mistake. Documentation sites routinely publish the same content in more than one place: a "latest" alias for versioned docs (/docs/latest/ mirroring /docs/v4/), a printable single-page version of a guide, an AMP or plain-text variant, a post cross-posted to a company blog or a platform like dev.to. Each of these needs a deliberate canonical decision rather than the default.

For version aliases, point the canonical of every page under /docs/latest/ at the corresponding versioned URL, or — more commonly — make latest the canonical and have the numbered copy of the current version canonicalize to it, so search results show a URL that does not go stale with each release. Older versions keep self-referencing canonicals but often get noindex once they are more than one or two majors behind; Versioned Documentation with Docusaurus discusses the trade-off.

For print or single-page versions, canonicalize to the multi-page original, since that is what readers should land on from search.

For syndication, the copy on the other site should carry a canonical pointing at your original. Platforms such as dev.to and Hashnode have a "canonical URL" field for exactly this. When the other site will not add one, publish there a few days after your own post so your version is indexed first, and link back prominently.

The rule in each case is the same: decide which URL you want to appear in search results, and make every copy say so.

Measured Impact

Five weeks after the fixes on the Eleventy blog:

Pitfalls & Rollback

• Canonicals to paginated page one. Page 2 of an archive is not a duplicate of page 1; each page should canonicalize to itself.
• Canonical to a redirecting URL. Search engines treat it as an error; point at the final URL.
• Canonical in the body. It must be in <head>; some Markdown-driven layouts accidentally output it inside <main>.
• Mixed-case URLs. Static hosts are usually case-sensitive; lowercase every generated path.
• Rollback: canonicals are template output and redirects are host rules; each can be reverted independently. Remove redirects first if a policy change goes wrong, because redirects are cached by browsers.

Conclusion

Duplicate content on a static site is almost always a policy mismatch between the generator, the links, the host and the canonical tags. Choose one URL shape, redirect every other shape at the host, generate the canonical and every other URL signal from one configured value, and check the output in CI. On the blog, that took four live variants per page down to one and cleared nearly every "different canonical" warning in Search Console.

FAQ

What is a self-referencing canonical?

It is a link rel canonical element whose href is the page's own preferred URL. Every indexable page should have one. It tells search engines which variant to index when the same content is reachable with tracking parameters, different casing or a missing trailing slash.

Is a canonical tag a substitute for a redirect?

No. A canonical is a hint that search engines usually follow, and it does nothing for readers or for link equity from other sites. Variants that should not exist, such as http or a missing slash, should be redirected with a 301 at the host. Canonicals handle the variants you cannot redirect.

Which trailing-slash policy is best?

Either works if it is applied everywhere. Directory-style URLs with a trailing slash map naturally to index.html files on static hosts. What matters is that the generator's links, the canonical tags, the sitemap and the host's redirects all agree.

Why would a preview deploy have the wrong canonical?

When the canonical is built from the request URL or a relative path instead of the configured production origin. Always build it from site configuration so previews point at production URLs, and also send noindex on previews.

Related

• Parent: Technical SEO for Static Sites — build-time SEO in full.
• Generating Sitemaps for Large Static Sites — sitemap URLs that match canonicals.
• Keeping Redirects Working After an SSG Migration — where many duplicates start.
• Netlify Redirects and Rewrites for Static Sites — host-level redirect rules.
• Trailing Slash and basePath in Next.js Static Export — the same policy in Next.js.