docs: document useHead behavior

docs/content/1.get-started/5.watch-outs.md

@@ -53,8 +53,8 @@ Read about the [Ionic Vue lifecycle hooks here](https://ionicframework.com/docs/
 Because of this, some expected functionality from Nuxt or other modules may not work or may require changes to get functioning:
 
 ::list{type="warning"}
-- **The composable `useHead()` will not work out of the box**.  
-  See [our cookbook page](/cookbook/page-metadata) for how to continue using `useHead()`
+- **Use the module's auto-imported `useHead()` composable**.
+  It accounts for Ionic's page lifecycle. See [our cookbook page](/cookbook/page-metadata) for usage details.
 - **Certain Vue Router components should not be used**.  
   This includes `<keep-alive>`, `<transition>`, and `<router-view>` - [read more here](https://ionicframework.com/docs/vue/lifecycle#how-ionic-framework-handles-the-life-of-a-page).
 ::

docs/content/3.cookbook/4.page-metadata.md

@@ -1,14 +1,52 @@
 ---
 title: useHead / Page Meta
-description: ""
+description: Manage page titles and head tags with the Ionic-compatible useHead composable.
 ---
 
+The module auto-imports an Ionic-compatible implementation of Nuxt's `useHead` composable. Ionic keeps inactive pages mounted, so Vue's unmount hooks cannot reliably remove their head entries.
+
+Inside a component, the composable associates each head entry with the current route. It disposes the route's entries on `onIonViewDidLeave` and restores them on `onIonViewDidEnter`.
+
+## Usage
+
+Use it like the standard Nuxt composable:
+
+```vue [pages/products/[id].vue]
+<script setup lang="ts">
+const route = useRoute()
+
+useHead({
+  title: () => `Product ${route.params.id}`,
+  meta: [
+    {
+      name: 'description',
+      content: 'View product details',
+    },
+  ],
+})
+</script>
+```
+
 ::callout{color="warning" icon="i-lucide-alert-triangle"}
-⚠️ This page is a stub and needs further information.
+Importing `useHead` directly from `@unhead/vue` bypasses the Ionic lifecycle handling.
 ::
 
-The composable `useHead()` will not work out of the box.
+## Usage outside components
+
+Since [nuxt-modules/ionic#825](https://github.com/nuxt-modules/ionic/pull/825), `useHead` also works without an active component instance. This is required by Nuxt plugins and modules such as `@nuxtjs/i18n`.
+
+```ts [plugins/app-head.ts]
+export default defineNuxtPlugin(() => {
+  useHead({
+    titleTemplate: title => title ? `${title} · My App` : 'My App',
+  })
+})
+```
 
-Please see this issue for reference: https://github.com/nuxt-modules/ionic/issues/6
+Without a component instance, the composable skips `useRoute`, `useRouter`, and the component lifecycle hooks. The head entry is registered directly and remains active until it is patched or disposed.
 
-Also see the documentation for use-head: https://nuxt.com/docs/api/composables/use-head
+The composable returns an entry with `patch()` and `dispose()` methods, matching the standard `useHead` API.
+
+::callout{color="info" icon="i-lucide-info"}
+See the [Nuxt `useHead` documentation](https://nuxt.com/docs/api/composables/use-head) for supported properties and reactive inputs.
+::