From e68a23a72381205285f05522ab6a453895a3bd73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Tue, 14 Mar 2023 15:24:41 +0100 Subject: [PATCH] docs: improve head section (#19673) --- docs/1.getting-started/5.seo-meta.md | 78 +++++++++-------------- docs/3.api/1.composables/use-head-safe.md | 22 ++++++- docs/3.api/1.composables/use-head.md | 5 +- 3 files changed, 51 insertions(+), 54 deletions(-) diff --git a/docs/1.getting-started/5.seo-meta.md b/docs/1.getting-started/5.seo-meta.md index d010b979c8..47e15e67d0 100644 --- a/docs/1.getting-started/5.seo-meta.md +++ b/docs/1.getting-started/5.seo-meta.md @@ -7,53 +7,40 @@ description: Improve your Nuxt app's SEO with powerful head config, composables Improve your Nuxt app's SEO with powerful head config, composables and components. -## App Head - -Providing an [app.head](/docs/api/configuration/nuxt-config#head) property in your `nuxt.config.ts` allows you to customize the head for your entire app. - -::alert{type=info} -This method does not allow you to provide reactive data, if you need global reactive data you can use `useHead` in `app.vue`. -:: - -Shortcuts are available to make configuration easier: `charset` and `viewport`. You can also provide any of the keys listed below in [Types](#types). - -### Defaults +## Defaults Out-of-the-box, Nuxt provides sane defaults, which you can override if needed. - `charset`: `utf-8` - `viewport`: `width=device-width, initial-scale=1` -### Example - -```ts{}[nuxt.config.ts] +```ts [nuxt.config.ts] export default defineNuxtConfig({ app: { head: { - charset: 'utf-16', - viewport: 'width=500, initial-scale=1', - title: 'My App', - meta: [ - // - { name: 'description', content: 'My amazing site.' } - ], + charset: 'utf-8', + viewport: 'width=device-width, initial-scale=1', } } }) ``` -:ReadMore{link="/docs/api/configuration/nuxt-config/#head"} +Providing an [`app.head`](/docs/api/configuration/nuxt-config#head) property in your [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt.config) allows you to customize the head for your entire app. -## Composable: `useHead` +::alert{type=info} +This method does not allow you to provide reactive data. We recommend to use `useHead()` in `app.vue`. +:: + +Shortcuts are available to make configuration easier: `charset` and `viewport`. You can also provide any of the keys listed below in [Types](#types). + +## `useHead` The `useHead` composable function allows you to manage your head tags in a programmatic and reactive way, powered by [Unhead](https://unhead.harlanzw.com/). As with all composables, it can only be used with a components `setup` and lifecycle hooks. -### Example - -```vue{}[app.vue] +```vue [app.vue] ``` -::ReadMore{link="/docs/api/composables/use-head"} -:: +We recommend to take a look at the [`useHead`](/docs/api/composables/use-head) and [`useHeadSafe`](/docs/api/composables/use-head-safe) composables. -## Composable: `useSeoMeta` and `useServerSeoMeta` +## `useSeoMeta` The `useSeoMeta` and `useServerSeoMeta` composables let you define your site's SEO meta tags as a flat object with full TypeScript support. @@ -79,11 +65,9 @@ This helps you avoid typos and common mistakes, such as using `name` instead of In most instances, the meta does not need to be reactive as robots will only scan the initial load. So we recommend using `useServerSeoMeta` as a performance-focused utility that will not do anything (or return a `head` object) on the client. -### Example +**Simple example:** -#### Simple - -```vue{}[app.vue] +```vue [app.vue] ``` -#### Reactive +**Reactive example:** -When inserting tags that are reactive, for example, from an API request, you should -use the computed getter syntax, the same as `useHead`. +When inserting tags that are reactive, for example, from an API request, you should use the computed getter syntax, the same as `useHead`. -```vue{}[app.vue] +```vue [app.vue] ``` -::ReadMore{link="https://unhead.harlanzw.com/guide/composables/use-seo-meta"} -:: +Read more on the [`useSeoMeta`](https://unhead.harlanzw.com/guide/composables/use-seo-meta) composable. + ## Components @@ -124,11 +107,9 @@ Because these component names match native HTML elements, it is very important t `` and `` can accept nested meta tags (for aesthetic reasons) but this has no effect on _where_ the nested meta tags are rendered in the final HTML. -### Example - -```vue{}[app.vue] +```vue [app.vue] @@ -204,7 +185,7 @@ It's recommended to use computed getters (`() => {}`) over computed (`computed(( :: -### Title Templates +### Title Template You can use the `titleTemplate` option to provide a dynamic template for customizing the title of your site. for example, by adding the name of your site to the title of every page. @@ -240,7 +221,8 @@ useHead({ script: [ { src: 'https://third-party-script.com', - tagPosition: 'bodyClose' // valid options are: 'head' | 'bodyClose' | 'bodyOpen' + // valid options are: 'head' | 'bodyClose' | 'bodyOpen' + tagPosition: 'bodyClose' } ] }) @@ -249,7 +231,7 @@ useHead({ ## Examples -### Usage With `definePageMeta` +### With `definePageMeta` Within your `pages/` directory, you can use `definePageMeta` along with `useHead` to set metadata based on the current route. @@ -280,7 +262,7 @@ useHead({ :ReadMore{link="/docs/guide/directory-structure/pages/#page-metadata"} -### Add Dynamic Title +### Dynamic Title In the example below, `titleTemplate` is set either as a string with the `%s` placeholder or as a `function`, which allows greater flexibility in setting the page title dynamically for each route of your Nuxt app: @@ -302,7 +284,7 @@ useHead({ `nuxt.config` is also used as an alternative way of setting the page title. However, `nuxt.config` does not allow the page title to be dynamic. Therefore, it is recommended to use `titleTemplate` in the `app.vue` file to add a dynamic title, which is then applied to all routes of your Nuxt app. -### Add External CSS +### External CSS The example below shows how you might enable Google Fonts using either the `link` property of the `useHead` composable or using the `` component: diff --git a/docs/3.api/1.composables/use-head-safe.md b/docs/3.api/1.composables/use-head-safe.md index eaef62eb4c..f90add71e0 100644 --- a/docs/3.api/1.composables/use-head-safe.md +++ b/docs/3.api/1.composables/use-head-safe.md @@ -4,10 +4,26 @@ description: The recommended way to provide head data with user input. # `useHeadSafe` -The useHeadSafe composable is a wrapper around the [useHead](/docs/api/composables/use-head) composable that restricts the input to only allow safe values. +The `useHeadSafe` composable is a wrapper around the [`useHead`](/docs/api/composables/use-head) composable that restricts the input to only allow safe values. -::ReadMore{link="https://unhead.harlanzw.com/guide/composables/use-head-safe"} -:: +## Usage + +You can pass all the same values as `useHead` +```ts +useHeadSafe({ + script: [ + { id: 'xss-script', innerHTML: 'alert("xss")' } + ], + meta: [ + { 'http-equiv': 'refresh', content: '0;javascript:alert(1)' } + ] +}) +// Will safely generate +// +// +``` + +Read more on [unhead documentation](https://unhead.harlanzw.com/guide/composables/use-head-safe). ## Type diff --git a/docs/3.api/1.composables/use-head.md b/docs/3.api/1.composables/use-head.md index 754b910909..f57b39fedf 100644 --- a/docs/3.api/1.composables/use-head.md +++ b/docs/3.api/1.composables/use-head.md @@ -4,10 +4,9 @@ description: useHead customizes the head properties of individual pages of your # `useHead` -The `useHead` composable function allows you to manage your head tags in a programmatic and reactive way, powered by [Unhead](https://unhead.harlanzw.com/). +The `useHead` composable function allows you to manage your head tags in a programmatic and reactive way, powered by [Unhead](https://unhead.harlanzw.com/). If the data comes from a user or other untrusted source, we recommend you check out [`useHeadSafe`](/docs/api/composables/use-head-safe) -::ReadMore{link="/docs/getting-started/seo-meta"} -:: +:ReadMore{link="/docs/getting-started/seo-meta"} ## Type