docs: document transformers (#1453)

Co-authored-by: Sébastien Chopin <[email protected]>
Co-authored-by: nobkd <[email protected]>

docs/content/4.api/4.advanced.md

@@ -77,3 +77,72 @@ export default defineNitroPlugin((nitroApp) => {
 })
 
 ```
+
+## Transformers
+
+Transformers are responsible for parsing and manipulating contents in the content module.
+Internally, the module has specific transformers for each content type to parse the raw content and prepare it for querying and rendering.
+
+You can create custom transformers to support new content types or improve functionalities of supported content types.
+
+1. Create your transformer. A transformer consists of 4 parts:
+  - `name`: Transformer name
+  - `extensions`: List of valid file extensions
+  - `parse`: If provided this function will be used to parsed the raw content
+  - `transform`: Received that parsed content and manipulate the content. 
+
+```ts [my-transformer.ts]
+// filename: my-transformer.ts
+import { defineTransformer } from '@nuxt/content/transformers'
+
+export default defineTransformer({
+  name: 'my-transformer',
+  extensions: ['.names'],
+  parse (_id, rawContent) {
+    return {
+      _id,
+      body: rawContent.trim().split('\n').map(line => line.trim()).sort()
+    }
+  }
+})
+
+```
+
+2. Define simple module to register transformer
+
+```ts [my-module.mjs]
+// filename: my-module.mjs
+import { resolve } from 'path'
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (_options, nuxt) {
+    nuxt.options.nitro.externals = nuxt.options.nitro.externals || {}
+    nuxt.options.nitro.externals.inline = nuxt.options.nitro.externals.inline || []
+    nuxt.options.nitro.externals.inline.push(resolve('./my-module'))
+    // @ts-ignore
+    nuxt.hook('content:context', (contentContext) => {
+      contentContext.transformers.push(resolve('./my-module/my-transformer.ts'))
+    })
+  }
+})
+
+```
+
+3. Register your module
+
+```ts [nuxt.config.ts]
+// filename: my-module.mjs
+import { resolve } from 'path'
+import { defineNuxtConfig } from '@nuxt/kit'
+import MyModule from './my-module'
+
+export default defineNuxtConfig({
+  modules: [
+    MyModule,
+    '@nuxt/content'
+  ]
+})
+```
+
+That's it. You can create `.names` files in content directory. Checkout transformer example.

examples/advanced/transformer/content/1.index.names

@@ -0,0 +1,4 @@
+John
+Joes
+Jessi
+Jason

examples/advanced/transformer/my-module/my-module.ts

@@ -0,0 +1,14 @@
+import { resolve } from 'path'
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (_options, nuxt) {
+    nuxt.options.nitro.externals = nuxt.options.nitro.externals || {}
+    nuxt.options.nitro.externals.inline = nuxt.options.nitro.externals.inline || []
+    nuxt.options.nitro.externals.inline.push(resolve('./my-module'))
+    // @ts-ignore
+    nuxt.hook('content:context', (contentContext) => {
+      contentContext.transformers.push(resolve('./my-module/my-transformer.ts'))
+    })
+  }
+})

examples/advanced/transformer/my-module/my-transformer.ts

@@ -0,0 +1,12 @@
+import { defineTransformer } from '@nuxt/content/transformers'
+
+export default defineTransformer({
+  name: 'my-transformer',
+  extensions: ['.names'],
+  parse (_id, rawContent) {
+    return {
+      _id,
+      body: rawContent.trim().split('\n').map(line => line.trim()).sort()
+    }
+  }
+})

examples/advanced/transformer/nuxt.config.ts

@@ -0,0 +1,9 @@
+import { defineNuxtConfig } from 'nuxt'
+import MyModule from './my-module/my-module'
+
+export default defineNuxtConfig({
+  modules: [
+    MyModule,
+    '@nuxt/content'
+  ]
+})

examples/advanced/transformer/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "example-hello-world",
+  "private": true,
+  "scripts": {
+    "build": "nuxt build",
+    "dev": "nuxt dev",
+    "generate": "nuxt generate",
+    "preview": "nuxt preview"
+  },
+  "devDependencies": {
+    "@nuxt/content": "npm:@nuxt/content-edge@latest",
+    "nuxt": "npm:nuxt3@latest"
+  }
+}

examples/advanced/transformer/pages/[...slug].vue

@@ -0,0 +1,25 @@
+<template>
+  <div class="content-page">
+    <ContentDoc v-slot="{ doc }">
+      <div>
+        {{ doc }}
+      </div>
+    </ContentDoc>
+  </div>
+</template>
+
+<script setup lang="ts">
+definePageMeta({
+  layout: 'default',
+  layoutTransition: false
+})
+</script>
+
+<style>
+.content-page {
+  height: calc(100vh - 60px);
+  max-height: calc(100vh - 60px);
+  padding: 1rem;
+  margin: 0;
+}
+</style>