Tiptap Docs

Custom nodes

Continuation from the AI agent chatbot guide

This guide continues the AI agent chatbot guide. Read it first.

If your document includes custom nodes or marks, configure schema awareness so the Server AI Toolkit can describe them correctly to your AI model.

Why configure custom nodes?

Without schema awareness, the AI model might generate content that your editor does not support, or miss custom elements entirely. Adding custom node metadata gives the model enough context to generate those elements reliably.

Get schema awareness data

Start by generating schema awareness data from your editor. The Server AI Toolkit uses this data to describe your document structure to the AI model.

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { getSchemaAwarenessData } from '@tiptap-pro/server-ai-toolkit'

const editor = new Editor({
  extensions: [StarterKit],
})

// Retrieve the schema awareness data
const schemaAwarenessData = getSchemaAwarenessData(editor)

Store the schema awareness data

The schema awareness data returned by getSchemaAwarenessData is a JSON-serializable object that you can store in your database. You don't need to generate it every time. Update it when your editor extensions or schema change.

Configure custom nodes

If your document contains custom Nodes and Marks, add the addJsonSchemaAwareness option to the extension configuration. This allows the AI model to understand and generate that custom node or mark accurately.

For example, if you have a custom node called 'alert', configure it like this:

import { Node } from '@tiptap/core'
import { z } from 'zod'

const CustomExtension = Node.create({
  name: 'alert',

  addAttributes() {
    return {
      type: {
        default: 'info',
        parseHTML: (element) => element.getAttribute('data-type'),
        renderHTML: (attributes) => {
          if (!attributes.type) {
            return {}
          }

          return {
            'data-type': attributes.type,
          }
        },
      },
    }
  },

  addJsonSchemaAwareness() {
    return {
      name: 'Alert Box',
      description: `A highlighted box used to display important information, warnings, or tips to the user.
It can contain inline content like text and formatting marks.`,
      attributes: {
        type: z
          .enum(['info', 'warning', 'error', 'success'])
          .describe(
            'The type of alert. Can be one of these 4 values: info, warning, error, or success',
          ),
      },
    }
  },

  parseHTML() {
    return [
      {
        tag: 'div[data-alert]',
      },
    ]
  },

  renderHTML({ HTMLAttributes }) {
    return ['div', { ...HTMLAttributes, 'data-alert': '' }, 0]
  },
})

The addJsonSchemaAwareness function should return an object with:

  • name (string): The human-readable name of the element in English
  • description? (string): Explanation of the element in English for the AI model
  • attributes? (Record<string, z.ZodTypeAny>): Possible attributes of the element, defined as Zod schemas that will be converted to JSON schemas

What about official Tiptap extensions?

Schema awareness for official Tiptap extensions is automatically supported by the Server AI Toolkit. They do not need to be configured. You can still override the default schema awareness information for official Tiptap extensions by extending the extension and adding the addJsonSchemaAwareness option.

Next steps

PreviouslyAdvanced guides