feat: add hooks guide documentation

- Introduce new guide section for hooks, including examples with hook callback
argument types.
- Move hooks examples from Guides/Plugins into Guides/Hooks.
- Add Hook documentation for new on/before/after request hooks.

docs/content/1.guide/7.plugins.md

@@ -43,39 +43,3 @@ export default defineNuxtConfig({
 })
 ```
 ::
-
-## Examples
-
-### Graceful Shutdown
-
-You can use plugins to register a hook that resolves when Nitro is closed.
-
-```ts
-export default defineNitroPlugin((nitro) => {
-  nitro.hooks.hookOnce("close", async () => {
-    // Will run when nitro is closed
-    console.log("Closing nitro server...")
-    await new Promise((resolve) => setTimeout(resolve, 500));
-    console.log("Task is done!");
-  });
-})
-```
-
-### Renderer Response
-
-You can use plugins to register a hook that modifies the renderer response.
-
-::alert
-This **only works** for render handler defined with [`renderer`](https://nitro.unjs.io/config#renderer) and won't be called for other api/server routes.
-In [Nuxt](https://nuxt.com/) this hook will be called for Server Side Rendered pages
-::
-
-```ts
-export default defineNitroPlugin((nitro) => {
-
-  nitro.hooks.hook('render:response', (response) => {
-    // Inspect or Modify the renderer response here
-    console.log(response)
-  })
-})
-```

docs/content/1.guide/8.hooks.md

@@ -0,0 +1,90 @@
+---
+icon: ri:anchor-fill
+---
+# Hooks
+
+Hooks allow extending the default behaviour of Nitro by registering custom functions to internal events.
+Nitro hooks are built with [unjs/hookable](https://github.com/unjs/hookable).
+
+Hooks can be registered in a Nitro app using [plugins](https://nitro.unjs.io/guide/plugins).
+
+## Available Hooks
+
+### Graceful Shutdown
+
+Hook that resolves when Nitro is closed.
+
+```ts
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hookOnce("close", async () => {
+    // Will run when nitro is closed
+    console.log("Closing nitro server...")
+    await new Promise((resolve) => setTimeout(resolve, 500))
+    console.log("Task is done!")
+  });
+})
+```
+
+### Renderer Response
+
+Hook that can access and modify the renderer response.
+
+::alert
+This **only works** for render handler defined with [`renderer`](https://nitro.unjs.io/config#renderer) and won't be called for other api/server routes.
+In [Nuxt](https://nuxt.com/) this hook will be called for Server Side Rendered pages
+::
+
+```ts
+export default defineNitroPlugin((nitro) => {
+
+  nitro.hooks.hook('render:response', (response: RenderResponse, { event: H3Event }) => {
+    // Inspect or Modify the renderer response here
+    console.log(response)
+  })
+})
+```
+
+### On Response
+
+Hook that resolves _after_ the app event handler is invoked but _before_ all other handlers.
+
+```ts
+export default defineNitroPlugin((nitro) => {
+
+  nitro.hooks.hook('on:response', (event: H3Event) => {
+    // Log or perhaps abort the request early
+    console.log(`Handling event for ${event.path}`)
+  })
+})
+```
+
+### Before Response
+
+Hook that resolves _after_ a handler returns a response but _before_ the response is sent.
+
+This hook is only called once per-request and not for each matched middleware or handler.
+
+```ts
+export default defineNitroPlugin((nitro) => {
+
+  nitro.hooks.hook('before:response', (response: Partial<Response>, { event: H3Event }) => {
+    // Inspect or Modify the response here
+      const result = randomInt(10) == 1 ? 'winner' : 'unlucky'
+      event.res.setHeader('Lucky-Winner', result)
+  })
+})
+```
+### After Response
+
+Hook that resolves _after_ a handler returns a response and _after_ the response is sent.
+
+```ts
+export default defineNitroPlugin((nitro) => {
+
+  nitro.hooks.hook('after:response', (response: Partial<Response>, { event: H3Event }) => {
+    // Inspect the response here
+    const contentType = event.node.res.getHeaders()["content-type"]
+    console.log(`Sent content: ${contentType}`)
+  })
+})
+```