Guides

Canonical URL

Copy for LLMs
Last updated by
Harlan Wilton
 in feat!: lowercase canonical URL (#41) Fixes #38.

Introduction

It's common to have multiple URLs pointing to the same content. For example, supporting a www. and non-www. domain or misc-matched trailing slashes.

The "main" domain is called the canonical URL. Ensuring a single canonical URL helps avoid duplicate content issues and confusion for end-users.

Learn more about canonical URLs with the Canonical Link Tag guide.

Canonical Head Tag

Nuxt SEO automatically sets a canonical URL meta tag for you. This tag is generated from the site URL and the current route path.

<head>
    <!-- ... -->
    <link rel="canonical" href="https://example.com/my-page" />
</head>

canonicalLowercase

By default, the canonical URL is generated in lowercase. This is to ensure that the canonical URL is consistent and avoids any issues with case sensitivity.

While it's recommended to keep this on, if you need to disable this feature, you can do so by setting canonicalLowercase to false.

nuxt.config.ts
export default defineNuxtConfig({
  seo: {
    canonicalLowercase: false
  }
})

canonicalQueryWhitelist

The canonical URL is generated from:

  • site.url. Your Site Config url.
  • $route.path: The current route path.
  • canonicalQueryWhitelist: A list of query parameters that should be included in the canonical URL.

By default, the canonicalQueryWhitelist includes a number of common query parameters that will modify the page content:

  • page
  • sort
  • filter
  • search
  • q
  • query

You can override this by providing your own list of query parameters that should be included in the canonical URL.

nuxt.config.ts
export default defineNuxtConfig({
  seo: {
    canonicalQueryWhitelist: ['myCustomQuery']
  }
})

Redirect To Canonical

In some cases it may be preferred to redirect all non-canonical URLs to the canonical URL.

This redirect is optional and disabled by default.

nuxt.config.ts
export default defineNuxtConfig({
  seo: {
    redirectToCanonicalSiteUrl: true
  }
})
Edit this page
Markdown For LLMs
Did this page help you?

Troubleshooting

Create minimal reproductions for Nuxt SEO Utils or just experiment with the module.

App Icons

Learn how metadata files work with logos.