docs(api): enhance useHead composable (#7072)

Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com>

docs/content/3.api/1.composables/use-head.md

@@ -1,48 +1,201 @@
 # `useHead`
 
-::ReadMore{link="/guide/features/head-management"}
+Nuxt provides the `useHead` composable to add and customize the head properties of individual pages of your Nuxt app. `useHead` uses [@vueuse/head](https://github.com/vueuse/head) under the hood.
-
-Nuxt provides a composable to update the head properties of your page with an [`MetaObject`](/api/composables/use-head/#metaobject) of meta properties with keys corresponding to meta tags:
-
-`title`, `base`, `script`, `noscript`, `style`, `meta` and `link`, as well as `htmlAttrs` and `bodyAttrs`. Alternatively, you can pass a function returning the object for reactive metadata.
-
-```js
-useHead(options: MetaObject)
-```
 
 ::alert{icon=👉}
-**`useHead` only works during `setup`**.
+**`useHead` must be placed within the `setup` function**.
 ::
 
-## Example
+## Type
 
-The example below changes the website's title in the `meta` and inserts a Google Font using the `link` property.
+```ts
+useHead(meta: Computable<MetaObject>): void
 
-```js
+interface MetaObject extends Record<string, any> {
-export default {
+  charset?: string
-  setup () {
+  viewport?: string
-    useHead({
+  meta?: Array<Record<string, any>>
-      meta: [
+  link?: Array<Record<string, any>>
-        { name: 'title' content: 'Nuxt 3 - The Hybrid Vue Framework' }
+  style?: Array<Record<string, any>>
-      ],
+  script?: Array<Record<string, any>>
-      link: [
+  noscript?: Array<Record<string, any>>
-        { rel: 'preconnect', href: 'https://fonts.googleapis.com' },
+  titleTemplate?: string | ((title: string) => string)
-        { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' },
+  title?: string
-        { rel: 'stylesheet', href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', crossorigin: '' },
+  bodyAttrs?: Record<string, any>
-      ]
+  htmlAttrs?: Record<string, any>
-    })
-  }
 }
 ```
 
-## `MetaObject`
+Application-wide configuration of the head metadata is possible through [nuxt.config](/api/configuration/nuxt.config#head), or by placing the `useHead` in the `app.vue` file.
 
-* **charset**: the character encoding in which the document is encoded => `<meta charset="<value>" />` (default: `'utf-8'`)
+::alert{type=info}
-* **viewport**: configuration of the viewport (the area of the window in which web content can be seen) => `<meta name="viewport" content="<value>" />` (default: `'width=device-width, initial-scale=1'`)
+The properties of `useHead` can be dynamic, accepting `ref`, `computed` and `reactive` properties. `meta` parameter can also accept a function returning an object to make the entire object reactive.
-* **meta**: array, each item maps to a newly-created `<meta>` element, where object properties map to attributes.
+::
-* **link**: array, each item maps to a newly-created `<link>` element, where object properties map to attributes.
-* **style**: array, each item maps to a newly-created `<style>` element, where object properties map to attributes.
-* **script**: array, each item maps to a newly-created `<script>` element, where object properties map to attributes.
-* **noscript**: array, each item maps to a newly-created `<noscript>` element, where object properties map to attributes.
 
-All elements in the meta object are optional. You can also pass only single values.
+## Parameters
+
+### `meta`
+
+**Type**: `MetaObject`
+
+An object accepting the following head metadata:
+
+- `charset`
+
+  **Type**: `string`
+
+  **Default**: `utf-8`
+
+  Specifies character encoding for the HTML document.
+
+- `viewport`
+
+  **Type**: `string`
+
+  **Default**: `width=device-width, initial-scale=1`
+
+  Configures the viewport (the user's visible area of a web page).
+
+- `meta`
+
+  **Type**: `Array<Record<string, any>>`
+
+  **Default**: `width=device-width, initial-scale=1`
+
+  Each element in the array is mapped to a newly-created `<meta>` tag, where object properties are mapped to the corresponding attributes.
+
+- `link`
+
+  **Type**: `Array<Record<string, any>>`
+
+  Each element in the array is mapped to a newly-created `<link>` tag, where object properties are mapped to the corresponding attributes.
+
+- `style`
+
+  **Type**: `Array<Record<string, any>>`
+
+  Each element in the array is mapped to a newly-created `<style>` tag, where object properties are mapped to the corresponding attributes.
+
+- `script`
+
+  **Type**: `Array<Record<string, any>>`
+
+  Each element in the array is mapped to a newly-created `<script>` tag, where object properties are mapped to the corresponding attributes.
+
+- `noscript`
+
+  **Type**: `Array<Record<string, any>>`
+
+  Each element in the array is mapped to a newly-created `<noscript>` tag, where object properties are mapped to the corresponding attributes.
+
+- `titleTemplate`
+
+  **Type**: `string` | `((title: string) => string)`
+
+  Configures dynamic template to customize the page title on an individual page.
+
+- `title`
+
+  **Type**: `string`
+
+  Sets static page title on an individual page.
+
+- `bodyAttrs`
+
+  **Type**: `Record<string, any>`
+
+  Sets attributes of the `<body>` tag. Each object property is mapped to the corresponding attribute.
+
+- `htmlAttrs`
+
+  **Type**: `Record<string, any>`
+
+  Sets attributes of the `<html>` tag. Each object property is mapped to the corresponding attribute.
+
+## Examples
+
+### Customize Metadata
+
+The example below changes the website's `title` and `description` using `meta` option of the `useHead` composable:
+
+```vue
+<script setup>
+  const title = ref('My App')
+  const description = ref('My amazing Nuxt app')
+
+  useHead({
+    title,
+    meta: [
+      {
+        name: 'description',
+        content: description
+      }
+    ]
+  })
+</script>
+```
+
+### Add 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:
+
+```vue [app.vue]
+<script setup>
+  useHead({
+    // as a string,
+    // where `%s` is replaced with the title
+    titleTemplate: '%s - Site Title',
+    // ... or as a function 
+    titleTemplate: (productCategory) => {
+      return productCategory
+        ? `${productCategory} - Site Title`
+        : 'Site Title'
+    }
+  })
+</script>
+```
+
+`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
+
+The example below inserts Google Fonts using the `link` property of the `useHead` composable:
+
+```vue
+<script setup>  
+  useHead({
+    link: [
+      { 
+        rel: 'preconnect', 
+        href: 'https://fonts.googleapis.com'
+      },
+      { 
+        rel: 'stylesheet', 
+        href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', 
+        crossorigin: '' 
+      }
+    ]
+  })
+</script>
+```
+
+### Add Third-party Script
+
+The example below inserts a third-party script using the `script` property of the `useHead` composable:
+
+```vue
+<script setup>
+  useHead({
+    script: [
+      {
+        src: 'https://third-party-script.com',
+        body: true
+      }
+    ]
+  })
+</script>
+```
+
+You can use the `body: true` option to add the above script at the end of the `<body>` tag.
+
+:ReadMore{link="/guide/features/head-management"}