update seo guide #3804
update seo guide #3804
Conversation
- Remove seemingly Nuxt 2 example - Add usages of useSeoMeta and indicate it's the primary way
WalkthroughThe docs replace definePageMeta and manual useHead/meta patterns with a new SEO composable useSeoMeta for per-page and layout metadata (title, description, ogTitle, ogType, ogSiteName, titleTemplate, etc.). Layouts now show useLocaleHead merged with useHead and a simplified markup structure. Page examples (index, about) demonstrate useSeoMeta with reactive values (computed) and titleTemplate. Language tag examples changed (en-US → en) with an explicit distinction between displayed language and language code. Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
docs/content/docs/02.guide/06.seo.md (5)
19-21: Tighten wording and fix grammar around thelanguageproperty.Clarifies BCP 47 requirement and fixes “an language”/flow.
-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, configure `i18n.locales` as an array of objects, each with a `language` property set to a valid BCP 47 language tag.-**NOTE**: while `code` is used to create prefixes for URLs and to set locales and can be any arbitrary value, `language` goes to `<html lang="...">` 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`. +**Note**: `code` is used for URL prefixes and locale selection and can be any arbitrary value; `language` is used for `<html lang="…">` and must be a [BCP 47](https://developer.mozilla.org/en-US/docs/Glossary/BCP_47_language_tag) tag. In most cases, both can share the same value (e.g., `en`, `es`).
29-38: Make the example consistent with the note (“language can match code”).Either use regionless tags for all three locales or regioned tags for all three. Given the PR goal, align all three with
code.{ code: 'en', - language: 'en' + language: 'en' }, { code: 'es', - language: 'es-ES' + language: 'es' }, { code: 'fr', - language: 'fr-FR' + language: 'fr' }Alternatively, switch all to regioned (
en-US,es-ES,fr-FR) and add a short sentence noting that matchingcodeis optional.
122-128: Optional: also setogTitleto match the computed page title.Keeps social previews consistent without repeating logic elsewhere.
useSeoMeta({ // Only override page-specific details title: computed(() => `${t('index.title')} ${locale.value}`), - description: computed(() => t('site.index.description')), + description: computed(() => t('site.index.description')), + ogTitle: computed(() => `${t('index.title')} ${locale.value}`), })
159-160: Fix grammar in merge sentence.-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. +If you also want to add your own metadata, call `useSeoMeta()`{lang="ts"}/`useHead()`{lang="ts"}. Your additional metadata will be merged with the global metadata that has already been defined.
162-170: Combine the twouseSeoMetacalls and localize the title.Also show
useI18nusage so the example works as written.<script setup> -// define page meta for layouts/default.vue -useSeoMeta({ - title: 'pages.title.about' -}) - -useSeoMeta({ - ogTitle: 'this is og title for about page', -}) +const { t } = useI18n() +// Define page-specific SEO +useSeoMeta({ + title: computed(() => t('pages.title.about')), + ogTitle: computed(() => t('pages.title.about')) +}) </script>
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/content/docs/02.guide/06.seo.md(4 hunks)
🔇 Additional comments (1)
docs/content/docs/02.guide/06.seo.md (1)
88-103: MovetitleTemplateintouseHeadand streamline SEO defaults
Pass a function touseHeadfor reactivity, removetitleTemplatefromuseSeoMeta, and defaultogTitleto the page title.-useHead({ - ...localeHead.value, - // Add something if needed -}) +useHead(() => ({ + ...localeHead.value, + // Global title strategy + titleTemplate: (titleChunk) => titleChunk ? `${titleChunk} - ${t('nav.brand')}` : t('nav.brand'), + // Add something if needed +})) -// Global SEO defaults -useSeoMeta({ - titleTemplate: (titleChunk) => { - return titleChunk ? `${titleChunk} - ${t('nav.brand')}` : t('nav.brand'); - }, - title: computed(() => t('site.name')), // Fallback when no page title - description: computed(() => t('site.description')), - ogType: 'website', - ogTitle: 'Wonderful OG title', - ogSiteName: computed(() => t('nav.brand')) -}) +// Global SEO defaults +useSeoMeta({ + // Fallbacks when no page-specific overrides + title: computed(() => t('site.name')), + description: computed(() => t('site.description')), + ogType: 'website', + ogTitle: computed(() => t('site.name')), // keep OG aligned with title by default + ogSiteName: computed(() => t('nav.brand')) +})
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (6)
docs/content/docs/02.guide/06.seo.md (6)
19-21: Grammar and clarity: article/property namingTighten wording and fix “an
language”.-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, configure the `locales` option as an array of objects, where each object has a `language` property set to a BCP 47 language tag.
66-66: Streamline guidance and wordingMinor style/clarity improvements and align phrasing with the recommended flow.
-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. +To avoid duplication, set global SEO metadata with [Meta Components](https://nuxt.com/docs/getting-started/seo-meta#components) in `app.vue` or in a [layout](https://nuxt.com/docs/guide/directory-structure/layouts), and override per page using [`useSeoMeta()`{lang="ts"}](https://nuxt.com/docs/api/composables/use-seo-meta) when needed.
77-78: Remove empty script block in app.vue exampleThe empty
<script setup>adds noise.-<script setup> -</script>
159-159: Typo and tone: definePageMeta noteFix typo and slightly tighten wording.
-**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. +**NOTE**: while you might be tempted to use [`definePageMeta`{lang="ts"}](https://nuxt.com/docs/4.x/api/utils/define-page-meta) to set the page title (and it works!), it’s not meant for that. Its main purpose is page-specific metadata such as [layout](https://nuxt.com/docs/guide/directory-structure/layouts) or `middleware`{lang="ts"}, not SEO or i18n metadata. The default choice should be [`useSeoMeta()`{lang="ts"}](https://nuxt.com/docs/api/composables/use-seo-meta) for supported fields, and `useHead` for everything else.
161-161: Grammar: merging phrasingFix prepositions/tense.
-When you call it with the additional metadata, `useSeoMeta()`{lang="ts"} will merge it global metadata that has already defined. +When you call it with additional metadata, `useSeoMeta()`{lang="ts"} merges it with the global metadata that has already been defined.
167-170: Localize the per-page title/OG title like other examplesKeep consistency with the index example by using
t(orcomputed(() => t(...))), and add the missinguseI18n()import.<script setup> -// add/override metadata coming from layouts/default.vue +// add/override metadata coming from layouts/default.vue +const { t } = useI18n() useSeoMeta({ - title: 'pages.title.about', - ogTitle: 'this is og title for about page', + title: computed(() => t('pages.title.about')), + ogTitle: computed(() => t('pages.about.ogTitle')), }) </script>
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
docs/content/docs/02.guide/06.seo.md(4 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/content/docs/02.guide/06.seo.md
[grammar] ~159-~159: Ensure spelling is correct
Context: ...ang="ts"} is not meant for it. Its main purprose is to set page-specific metadata, such ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (1)
docs/content/docs/02.guide/06.seo.md (1)
122-128: Good use of useSeoMeta with reactive i18n valuesThis example correctly demonstrates reactive
title/descriptionviacomputedandt.
| useHead({ | ||
| ...localeHead.value, | ||
| // Add something if needed | ||
| }) | ||
There was a problem hiding this comment.
Fix reactivity loss when passing localeHead to useHead
Spreading localeHead.value into a plain object makes the head static and it won’t update on locale changes. Wrap in a function (or pass the computed directly) to keep it reactive.
-useHead({
- ...localeHead.value,
- // Add something if needed
-})
+useHead(() => ({
+ ...localeHead.value,
+ // Add something if needed
+}))Alternative:
-useHead({
- ...localeHead.value
-})
+useHead(localeHead)
+useHead({ /* your extra static entries */ })📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| useHead({ | |
| ...localeHead.value, | |
| // Add something if needed | |
| }) | |
| useHead(() => ({ | |
| ...localeHead.value, | |
| // Add something if needed | |
| })) |
🤖 Prompt for AI Agents
In docs/content/docs/02.guide/06.seo.md around lines 88 to 92, spreading
localeHead.value into a plain object makes the head static and loses reactivity;
instead pass a function that returns the reactive value or pass the computed
directly to useHead so it updates on locale changes — replace useHead({
...localeHead.value, /* extras */ }) with useHead(() => ({ ...localeHead.value,
/* extras */ })) or simply useHead(localeHead) as appropriate.
There was a problem hiding this comment.
This doesn't seem needed for SEO (as generally there is no need to be reactive for non-title tags). So I'd ignore this comment.
There was a problem hiding this comment.
@okainov, understood! You're right that for SEO metadata like hreflang links, canonical URLs, and og:locale tags, reactivity typically isn't crucial since these values are generally static per page/route. I appreciate the clarification about your specific use case requirements.
(\ /)
( ._.)
o_(")(") *nods thoughtfully*
languagewith example of the same value ascode🔗 Linked issue
#3803
📚 Description
Summary by CodeRabbit