nuxt · danielroe · Oct 12, 2022 · Oct 5, 2022 · Oct 5, 2022 · Oct 5, 2022
diff --git a/docs/content/1.getting-started/5.seo-meta.md b/docs/content/1.getting-started/5.seo-meta.md
@@ -1,87 +1,84 @@
 ---
 navigation.icon: uil:file-search-alt
-description: Nuxt provides good default values for meta tags, but you can override these if you need to.
+description: Improve your Nuxt apps SEO with powerful head config, composables and components.
 ---
 
 # SEO and Meta
 
-Out-of-the-box, Nuxt provides good default values for `charset` and `viewport` meta tags, but you can override these if you need to, as well as customize other meta tags for your site in several different ways.
+Improve your Nuxt apps SEO with powerful head config, composables and components.
 
-:ReadMore{link="/api/configuration/nuxt-config#head"}
+## App Head
 
-## `useHead` Composable
+Providing an [app.head](/api/configuration/nuxt-config#head) property in your `nuxt.config.ts` allows you to customize the head for your entire app.
 
-Within your `setup` function, you can call `useHead` with an object of meta properties with keys corresponding to meta tags: `title`, `titleTemplate`, `base`, `script`, `noscript`, `style`, `meta` and `link`, as well as `htmlAttrs` and `bodyAttrs`. There are also two shorthand properties, `charset` and `viewport`, which set the corresponding meta tags. Alternatively, you can pass a function returning the object for reactive metadata.
-
-For example:
+::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`.
+::
 
-```vue
-<script setup>
-useHead({
-  title: 'My App',
-  // or, instead:
-  // titleTemplate: (title) => `My App - ${title}`,
-  viewport: 'width=device-width, initial-scale=1, maximum-scale=1',
-  charset: 'utf-8',
-  meta: [
-    { name: 'description', content: 'My amazing site.' }
-  ],
-  bodyAttrs: {
-    class: 'test'
-  }
-})
-</script>
-```
+Shortcuts are available to make configuration easier: `charset` and `viewport`. Otherwise refer to the [Types](#types).
 
-::ReadMore{link="/api/composables/use-head"}
-::
+### Defaults
 
-## Title Templates
+Out-of-the-box, Nuxt provides sane defaults, which you can override if needed.
 
-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.
+- `charset`: `utf-8`
+- `viewport`: `width=device-width, initial-scale=1`
 
-The `titleTemplate` can either be a string, where `%s` is replaced with the title, or a function. If you want to use a function (for full control), then this cannot be set in your `nuxt.config`, and it is recommended instead to set it within your `app.vue` file, where it will apply to all pages on your site:
+### Example
 
-```vue [app.vue]
-<script setup>
-  useHead({
-    titleTemplate: (titleChunk) => {
-      return titleChunk ? `${titleChunk} - Site Title` : 'Site Title';
+```ts{}[nuxt.config.ts]
+export default defineNuxtConfig({
+  app: {
+    head: {
+      charset: 'utf-16',
+      viewport: 'width=500, initial-scale=1', 
+      title: 'My App',
+      meta: [
+        // <meta name="description" content="My amazing site">
+        { name: 'description', content: 'My amazing site.' }
+      ],
     }
-  })
-</script>
+  }
+})
 ```
 
-Now, if you set the title to `My Page` with `useHead` on another page of your site, the title would appear as 'My Page - Site Title' in the browser tab. You could also pass `null` to default to the site title.
+:ReadMore{link="/api/configuration/nuxt-config/#head"}
 
-## Body Meta Tags
+## Composable: `useHead`
 
-You can use the `body: true` option on the `link` and `script` meta tags to append them to the end of the `<body>` tag.
+The `useHead` composable function allows you to manage your head tags in a programmatic and reactive way, powered by [@vueuse/head](https://github.com/vueuse/head).
 
-For example:
+As with all composables, it can only be used with a components `setup` and lifecycle hooks.
 
-```vue
-<script setup>
+### Example
+
+```vue{}[app.vue]
+<script setup lang="ts">
 useHead({
-  script: [
-    {
-      src: 'https://third-party-script.com',
-      body: true
-    }
-  ]
+  title: 'My App',
+  meta: [
+    { name: 'description', content: 'My amazing site.' }
+  ],
+  bodyAttrs: {
+    class: 'test'
+  },
+  script: [ { children: 'console.log(\'Hello world\') } ]
 })
 </script>
 ```
 
-## Meta Components
+::ReadMore{link="/api/composables/use-head"}
+::
+
+## Components
 
 Nuxt provides `<Title>`, `<Base>`, `<Script>`, `<NoScript>`, `<Style>`, `<Meta>`, `<Link>`, `<Body>`, `<Html>` and `<Head>` components so that you can interact directly with your metadata within your component's template.
 
 Because these component names match native HTML elements, it is very important that they are capitalized in the template.
 
 `<Head>` and `<Body>` 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.
 
-For example:
+### Example
 
 <!-- @case-police-ignore html -->
 
@@ -103,7 +100,120 @@ const title = ref('Hello World')
 </template>
 ```
 
-## Example: Usage With `definePageMeta`
+## Types
+
+The below is the non-reactive types used for `useHead`, `app.head` and components.
+
+```ts
+interface MetaObject {
+  title?: string
+  titleTemplate?: string | ((title?: string) => string)
+  base?: Base
+  link?: Link[]
+  meta?: Meta[]
+  style?: Style[]
+  script?: Script[]
+  noscript?: Noscript[];
+  htmlAttrs?: HtmlAttributes;
+  bodyAttrs?: BodyAttributes;
+}
+```
+
+See [zhead](https://github.com/harlan-zw/zhead/tree/main/packages/schema/src) for more detailed types.
+
+## Features
+
+### Reactivity
+
+Reactivity is supported on all properties, as computed, computed getter refs and reactive.
+
+It's recommended to use computed getters (`() => {}`) over computed (`computed(() => {})`).
+
+::code-group
+
+  ```vue [useHead]
+  <script setup lang="ts">
+  const desc = ref('My amazing site.')
+
+  useHead({
+    meta: [
+      { name: 'description', content: desc }
+    ],
+  })
+  </script>
+  ```
+
+  ```vue [Components]
+  <script setup>
+  const desc = ref('My amazing site.')
+  </script>
+  <template>
+  <div>
+    <Meta name="description" :content="desc" />
+  </div>
+  </template>
+  ```
+
+::
+
+### Title Templates
+
+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.
+
+The `titleTemplate` can either be a string, where `%s` is replaced with the title, or a function.
+
+If you want to use a function (for full control), then this cannot be set in your `nuxt.config`, and it is recommended instead to set it within your `app.vue` file, where it will apply to all pages on your site:
+
+::code-group
+
+  ```vue [useHead]
+  <script setup lang="ts">
+    useHead({
+      titleTemplate: (titleChunk) => {
+        return titleChunk ? `${titleChunk} - Site Title` : 'Site Title';
+      }
+    })
+  </script>
+  ```
+
+::
+
+Now, if you set the title to `My Page` with `useHead` on another page of your site, the title would appear as 'My Page - Site Title' in the browser tab. You could also pass `null` to default to the site title.
+
+### Body Tags
+
+You can use the `body: true` option on the `link` and `script` meta tags to append them to the end of the `<body>` tag.
+
+For example:
+
+::code-group
+
+  ```vue [useHead]
+  <script setup lang="ts">
+  useHead({
+    script: [
+      {
+        src: 'https://third-party-script.com',
+        body: true
+      }
+    ]
+  })
+  </script>
+  ```
+
+  ```vue [Components]
+  <template>
+  <div>
+    <Script src="https://third-party-script.com" body="true" />
+  </div>
+  </template>
+  ```
+
+::
+
+## Examples
+
+### Usage With `definePageMeta`
 
 Within your `pages/` directory, you can use `definePageMeta` along with `useHead` to set metadata based on the current route.
 
@@ -132,3 +242,60 @@ useHead({
 :LinkExample{link="/examples/composables/use-head"}
 
 :ReadMore{link="/guide/directory-structure/pages/#page-metadata"}
+
+### 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:
+
+::code-group
+
+  ```vue [useHead]
+  <script setup lang="ts">  
+  useHead({
+    link: [
+      { 
+        rel: 'preconnect', 
+        href: 'https://fonts.googleapis.com'
+      },
+      { 
+        rel: 'stylesheet', 
+        href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', 
+        crossorigin: '' 
+      }
+    ]
+  })
+  </script>
+  ```
+
+  ```vue [Components]
+  <template>
+  <div>
+    <Link rel="preconnect" href="https://fonts.googleapis.com" />
+    <Link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" crossorigin="" />
+  </div>
+  </template>
+  ```
+
+::