diff --git a/docs/content/4.api/4.advanced.md b/docs/content/4.api/4.advanced.md index b7e130a3c..c28f546a1 100644 --- a/docs/content/4.api/4.advanced.md +++ b/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. \ No newline at end of file diff --git a/examples/advanced/transformer/content/1.index.names b/examples/advanced/transformer/content/1.index.names new file mode 100644 index 000000000..0b1f1c911 --- /dev/null +++ b/examples/advanced/transformer/content/1.index.names @@ -0,0 +1,4 @@ +John +Joes +Jessi +Jason \ No newline at end of file diff --git a/examples/advanced/transformer/my-module/my-module.ts b/examples/advanced/transformer/my-module/my-module.ts new file mode 100644 index 000000000..ef5733b78 --- /dev/null +++ b/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')) + }) + } +}) diff --git a/examples/advanced/transformer/my-module/my-transformer.ts b/examples/advanced/transformer/my-module/my-transformer.ts new file mode 100644 index 000000000..7e777ce17 --- /dev/null +++ b/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() + } + } +}) diff --git a/examples/advanced/transformer/nuxt.config.ts b/examples/advanced/transformer/nuxt.config.ts new file mode 100644 index 000000000..5795550d6 --- /dev/null +++ b/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' + ] +}) diff --git a/examples/advanced/transformer/package.json b/examples/advanced/transformer/package.json new file mode 100644 index 000000000..3ef862d24 --- /dev/null +++ b/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" + } +} diff --git a/examples/advanced/transformer/pages/[...slug].vue b/examples/advanced/transformer/pages/[...slug].vue new file mode 100644 index 000000000..2aa84efb3 --- /dev/null +++ b/examples/advanced/transformer/pages/[...slug].vue @@ -0,0 +1,25 @@ + + + + +