From a1dcf1a4ab6fdbdb45d79361d2f416f384394e07 Mon Sep 17 00:00:00 2001 From: Oleg Kainov Date: Wed, 3 Sep 2025 11:07:06 +0200 Subject: [PATCH 1/2] update seo guide - Remove seemingly Nuxt 2 example - Add usages of useSeoMeta and indicate it's the primary way --- docs/content/docs/02.guide/06.seo.md | 74 +++++++++++++++++----------- 1 file changed, 46 insertions(+), 28 deletions(-) diff --git a/docs/content/docs/02.guide/06.seo.md b/docs/content/docs/02.guide/06.seo.md index 61e706c7c..d13c781a6 100644 --- a/docs/content/docs/02.guide/06.seo.md +++ b/docs/content/docs/02.guide/06.seo.md @@ -16,7 +16,9 @@ Here are the specific optimizations and features that it enables: ## Requirements -To leverage the SEO benefits, you must configure the `locales` option as an array of objects, where each object has an `language` option set to the locale language tags: +To leverage the SEO benefits, you must configure the `locales` option as an array of objects, where each object has an `language` option set to the locale language tags. + +**NOTE**: while `code` is used to create prefixes for URLs and to set locales and can be any arbitrary value, `language` goes to `` and must be [BCP 47](https://developer.mozilla.org/en-US/docs/Glossary/BCP_47_language_tag). In most cases though both can share the same value like `en` or `es`. ```ts [nuxt.config.ts] export default defineNuxtConfig({ @@ -24,7 +26,7 @@ export default defineNuxtConfig({ locales: [ { code: 'en', - language: 'en-US' + language: 'en' }, { code: 'es', @@ -61,7 +63,7 @@ The `useLocaleHead()`{lang="ts"} is a composable function, Calling that composab To enable SEO metadata, declare a `setup` function in one of the places specified above and make it return the result of a `useLocaleHead()`{lang="ts"} function call. -To avoid duplicating the code, it's recommended to set globally with [Meta Components](https://nuxt.com/docs/getting-started/seo-meta#components) in [layout components](https://nuxt.com/docs/guide/directory-structure/layouts) and override some values per-page Vue component like [`definePageMeta()`{lang="ts"}](https://nuxt.com/docs/guide/directory-structure/pages#page-metadata), if necessary. +To avoid duplicating the code, it's recommended to set globally with [Meta Components](https://nuxt.com/docs/getting-started/seo-meta#components) in `app.vue` or [layout components](https://nuxt.com/docs/guide/directory-structure/layouts) and override some values per-page Vue component like [`useSeoMeta()`{lang="ts"}](https://nuxt.com/docs/api/composables/use-seo-meta), if necessary. ::code-group @@ -71,44 +73,60 @@ To avoid duplicating the code, it's recommended to set globally with [Meta Compo + + ``` ```vue [layouts/default.vue] ``` ```vue [pages/index.vue] From a02fec6c1daaa135b091555db57e66eb5388f645 Mon Sep 17 00:00:00 2001 From: Oleg Kainov Date: Wed, 3 Sep 2025 11:42:51 +0200 Subject: [PATCH 2/2] clarify useHead/useSeoMeta/definePageMeta --- docs/content/docs/02.guide/06.seo.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/content/docs/02.guide/06.seo.md b/docs/content/docs/02.guide/06.seo.md index d13c781a6..1b5e9daa7 100644 --- a/docs/content/docs/02.guide/06.seo.md +++ b/docs/content/docs/02.guide/06.seo.md @@ -156,18 +156,19 @@ Check out the options you can pass to the `useLocaleHead()`{lang="ts"} in the [c That's it! -If you also want to add your own metadata, you have to call `useSeoMeta()`{lang="ts"}/`useHead()`{lang="ts"}. When you call it with the additional metadata, `useSeoMeta()`{lang="ts"}/`useHead()`{lang="ts"} will merge it global metadata that has already defined. +**NOTE**: while you might be tempted to use [`definePageMeta`{lang="ts"}](https://nuxt.com/docs/4.x/api/utils/define-page-meta) to set page title (and it works!), `definePageMeta`{lang="ts"} is not meant for it. Its main purprose is to set page-specific metadata, such as [layout](https://nuxt.com/docs/guide/directory-structure/layouts) or `middleware`{lang="ts"} and not to manipulate SEO and/or i18n-specific metadata. Default choice should be [`useSeoMeta()`{lang="ts"}](https://nuxt.com/docs/api/composables/use-seo-meta) for fields that it supports and `useHead` for everything else. + +If you also want to add your own metadata, you have to call `useSeoMeta()`{lang="ts"}. When you call it with the additional metadata, `useSeoMeta()`{lang="ts"} will merge it global metadata that has already defined. ```vue [pages/about/index.vue]