update docs

YousefED · YousefED · commit 8e0fb6ca6592 · 2025-05-19T14:28:07.000+02:00
diff --git a/docs/pages/docs/ai.mdx b/docs/pages/docs/ai.mdx
@@ -15,29 +15,52 @@ Users can work with an AI agent to edit, write and format their documents.
 
 [VIDEO]
 
-- Try the [basic AI demo](/examples/ai/minimal)
-- ..or try different models in the [AI playground](/examples/ai/playground)
-- [Setup documentation](/docs/ai/getting-started)
-- TODO
+
+<Callout>
+  BlockNote AI is now in early preview - we'd love to hear your feedback!
+  We also collaborate with companies to help with the integration or implement
+  more advanced AI related functionality. [Get in touch](/about).
+</Callout>
 
 ## Features
 
 BlockNote AI has been designed to be fully customizable.
 BlockNote shows exactly what the AI agent is doing - making it easy for users to
 work hand in hand with AI agents.
 
-- Customize commands to write new content or update existing content or formatting
-- Streaming support for quick feedback
-- Users can accept or reject AI suggestions
-- Connect any LLM model (from Llama to OpenAI, Mistral or Anthropic)
-- Customizable prompts
-- Built directly on the [Vercel AI SDK](https://sdk.vercel.ai)
-- No dependency on our backend - use your own infrastructure or connect directly to a hosted LLM API
-- Feature requests? [Get in touch](/about).
+### User Experience
+
+- **Interactive AI Suggestions**: Users can accept or reject AI suggestions with a simple click, maintaining full control over their content
+- **Real-time Feedback**: Streaming support provides immediate responses, making the AI interaction feel natural and responsive
+- **Transparent Operations**: See exactly what the AI is doing at each step, with clear visual indicators of AI actions
+
+### Technical Capabilities
+
+- **Flexible Command System**: Customize commands to write or update existing content and formatting
+- **Multi-step Workflows**: Support for "Human in the Loop" workflows where users can guide the AI
+- **Model Agnostic**: Connect any LLM model (from Llama to OpenAI, Mistral or Anthropic)
+- **Customizable Prompts**: Fine-tune AI behavior with custom prompts and instructions
+- **No Backend Required**: Use your own infrastructure or connect directly to a hosted LLM API
+
+### Integration
+
+- **Built on Vercel AI SDK**: Leverages the power of the [Vercel AI SDK](https://sdk.vercel.ai) for reliable AI integration
+- **Easy Setup**: Get started quickly with minimal configuration
+- **Completely Customizable**: Fully customizable commands and UI elements
 
 <Callout type={"info"}>
   This feature is provided by the `@blocknote/xl-ai`. `xl-` packages are fully
   open source, but released under a copyleft license. A commercial license for
   usage in closed source, proprietary products comes as part of the [Business
   subscription](/pricing).
 </Callout>
+
+### Next Steps
+
+- Try the [basic AI demo](/examples/ai/minimal) to see it in action
+- Explore different models in the [AI playground](/examples/ai/playground)
+- Check out the [setup documentation](/docs/ai/getting-started)
+- Learn about [customizing commands](/docs/ai/custom-commands)
+- Review the [API Reference](/docs/ai/reference)
+
+Have a feature request or need help with integration? [Get in touch](/about) with our team.
diff --git a/docs/pages/docs/ai/_meta.json b/docs/pages/docs/ai/_meta.json
@@ -1,5 +1,5 @@
 {
-  "setup": "Editor Setup",
-  "custom-commands": "Customizing Commands",
+  "getting-started": "Getting Started",
+  "custom-commands": "Custom Commands",
   "reference": "Reference"
 }
diff --git a/docs/pages/docs/ai/custom-commands.mdx b/docs/pages/docs/ai/custom-commands.mdx
@@ -1,4 +1,14 @@
-# Customizing AI Menu Items (commands)
+---
+title: Custom AI Commands
+description: Customize the AI menu items (commands) in your BlockNote rich text editor
+imageTitle: BlockNote AI
+path: /docs/ai/custom-commands
+---
+
+import { Example } from "@/components/example";
+import { Callout } from "nextra/components";
+
+# Custom AI Menu Items (commands)
 
 A central part when users are interacting with the AI agent is the _AI Suggestion Menu_ where users can enter a custom prompt or select a pre-defined command.
 
@@ -8,7 +18,7 @@ This menu is easy to customize so you can expose commands fine-tuned to your app
 
 ## Defining your own commands
 
-First, we define a new AI command, let's create one that makes selected text more casual
+First, we define a new AI command. Let's create one that makes selected text more informal.
 
 ```tsx
 import { AIMenuSuggestionItem, getAIExtension } from "@blocknote/xl-ai";
@@ -39,7 +49,7 @@ export const makeInformal = (
 });
 ```
 
-Now, we let's create a customized AI Menu to show this command when the user has selected some text and opened the AI menu:
+Now, we create a customized AI Menu to show this command when the user has selected some text and opened the AI menu:
 
 ```tsx
 import { AIMenu, getDefaultAIMenuItems } from "@blocknote/xl-ai";
@@ -80,7 +90,7 @@ function CustomAIMenu() {
 
 Now, let's use this custom AI Menu in our app:
 
-````tsx
+```tsx
 <BlockNoteView
         editor={editor}
         formattingToolbar={false}
@@ -106,6 +116,4 @@ Have a look at the full example below, where we also add an AI menu item when no
 # Reference
 
 So far, we've added basic commands to the editor, but it's possible to completely customize low level prompts sent to the LLM.
-To learn in detail about the methods available such as `callLLM`, continue to the [AI reference docs](/docs/ai/reference).
-
-````
+To learn in detail about the `callLLM` method used in this guide, continue to the [AI reference docs](/docs/ai/reference).
diff --git a/docs/pages/docs/ai/getting-started.mdx b/docs/pages/docs/ai/getting-started.mdx
@@ -1,15 +1,17 @@
 ---
-title: AI Rich Text Editing
+title: Getting Started with BlockNote AI
 description: Add AI functionality to your BlockNote rich text editor
 imageTitle: BlockNote AI
-path: /docs/ai
+path: /docs/ai/getting-started
 ---
 
 import { Example } from "@/components/example";
 import { Callout } from "nextra/components";
 
 # Getting Started with BlockNote AI
 
+This guide walks you through the steps to add AI functionality to your BlockNote rich text editor.
+
 First, install the `@blocknote/xl-ai` package:
 
 ```bash
@@ -53,12 +55,8 @@ Now, you can create the editor with the AI Extension enabled:
 import { createBlockNoteEditor } from "@blocknote/core";
 import { BlockNoteAIExtension } from "@blocknote/xl-ai";
 import {
-  AIToolbarButton,
-  AIMenuController,
   locales as aiLocales,
   createAIExtension,
-  createBlockNoteAIClient,
-  getAISlashMenuItems,
 } from "@blocknote/xl-ai";
 
 const editor = createBlockNoteEditor({
@@ -75,13 +73,17 @@ const editor = createBlockNoteEditor({
 });
 ```
 
-### The `createAIExtension` method
-
-TODO
+See the [API Reference](/docs/ai/reference) for more information on the `createAIExtension` method.
 
 ## Adding AI UI elements
 
 Now, the only thing left to do is to customize the UI elements of your editor.
+We want to:
+
+- add an AI button to the formatting toolbar (shown when selecting text)
+- add an AI option to the slash menu (shown when typing a `/`)
+
+We do this by disabling the default FormattingToolbar and SuggestionMenu and adding our own. See [Changing UI Elements](/docs/ui-components) for more information.
 
 ```tsx
 <BlockNoteView
@@ -105,4 +107,6 @@ Now, the only thing left to do is to customize the UI elements of your editor.
 
 # Full Example
 
+See the full example code and live demo. Select some text and click the AI (stars) button, or type `/ai` anywhere in the editor to access AI functionality.
+
 <Example name="ai/minimal" />
diff --git a/docs/pages/docs/ai/reference.mdx b/docs/pages/docs/ai/reference.mdx
@@ -1,3 +1,13 @@
+---
+title: BlockNote AI Reference
+description: Reference documentation for the BlockNote AI extension
+imageTitle: BlockNote AI
+path: /docs/ai/reference
+---
+
+import { Example } from "@/components/example";
+import { Callout } from "nextra/components";
+
 # BlockNote AI Reference
 
 ## `createAIExtension`
@@ -8,14 +18,16 @@ Use `createAIExtension` to create a new AI new AI Extension that can be register
 // Usage:
 const aiExtension = createAIExtension(opts: AIExtensionOptions);
 
-// Definition:
+// Definitions:
+function createAIExtension(options: AIExtensionOptions): (editor: BlockNoteEditor) => AIExtension;
+
 type AIExtensionOptions = {
-  /**
+    /**
    * The default language model to use for LLM calls
    */
   model: LanguageModel;
   /**
-   * Whether to stream the LLM response (not all models might support this)
+   * Whether to stream the LLM response
    * @default true
    */
   stream?: boolean;
@@ -24,10 +36,10 @@ type AIExtensionOptions = {
    * html format is recommended, the other formats are experimental
    * @default llmFormats.html
    */
-  dataFormat?: "html" | "json" | "markdown";
+  dataFormat?: LLMFormat;
   /**
    * A function that can be used to customize the prompt sent to the LLM
-   * @default undefined
+   * @default the default prompt builder for the selected {@link dataFormat}
    */
   promptBuilder?: PromptBuilder;
   /**
@@ -44,7 +56,7 @@ type AIExtensionOptions = {
 Use `getAIExtension` to retrieve the AI extension instance registered to the editor:
 
 ```typescript
-getAIExtension(editor: BlockNoteEditor): AIExtension;
+function getAIExtension(editor: BlockNoteEditor): AIExtension;
 ```
 
 ## `AIExtension`
@@ -66,8 +78,8 @@ class AIExtension {
     aiMenuState:
       | ({
           /**
-           * The ID of the block that the AI menu is open at
-           * this changes as the AI is making changes to the document
+           * The ID of the block that the AI menu is opened at.
+           * This changes as the AI is making changes to the document
            */
           blockId: string;
         } & (
@@ -145,7 +157,8 @@ class AIExtension {
 
 ### `LLMRequestOptions`
 
-Requests an LLM are made by calling `callLLM` on the `AIExtension` object.
+Requests to a LLM are made by calling `callLLM` on the `AIExtension` object.
+This takes a `LLMRequestOptions` object as an argument.
 
 ```typescript
 type LLMRequestOptions = {
@@ -253,12 +266,12 @@ type LLMRequestOptions = {
 };
 ```
 
-## (advanced) `doLLMRequest`
+## `doLLMRequest` (advanced)
 
 The `CallLLM` function automatically passes the default options set in the `AIExtension` to the LLM request.
-It also handles the LLM response and the AI menu state
+It also handles the LLM response and updates the state of the AI menu accordingly.
 
-For advanced use cases, you can also directly use the `doLLMRequest` to issue an LLM request.
+For advanced use cases, you can also directly use the lower-level `doLLMRequest` function to issue an LLM request directly.
 In this case, you will need to manually handle the response.
 
 ```typescript
@@ -287,6 +300,15 @@ To implement a custom `PromptBuilder`, you can use the `promptHelpers` provided
 We recommend looking at the [default PromptBuilder](https://github.com/TypeCellOS/BlockNote/blob/main/packages/xl-ai/src/api/formats/html-blocks/defaultHTMLPromptBuilder.ts) implementations as a starting point to implement your own.
 
 ```typescript
+/**
+ * A PromptBuilder is a function that takes a BlockNoteEditor and details about the user's promot
+ * and turns it into an array of CoreMessage (AI SDK) to be passed to the LLM.
+ */
+type PromptBuilder = (
+  editor: BlockNoteEditor<any, any, any>,
+  opts: PromptBuilderInput,
+) => Promise<Array<CoreMessage>>;
+
 /**
  * The input passed to a PromptBuilder
  */
@@ -311,15 +333,6 @@ type PromptBuilderInput = {
    */
   previousMessages?: Array<CoreMessage>;
 };
-
-/**
- * A PromptBuilder is a function that takes a BlockNoteEditor and details about the user's promot
- * and turns it into an array of CoreMessage (AI SDK) to be passed to the LLM.
- */
-type PromptBuilder = (
-  editor: BlockNoteEditor<any, any, any>,
-  opts: PromptBuilderInput,
-) => Promise<Array<CoreMessage>>;
 ```
 
 ## Formats
diff --git a/examples/09-ai/01-minimal/README.md b/examples/09-ai/01-minimal/README.md
@@ -2,11 +2,10 @@
 
 This example shows the minimal setup to add AI integration to your BlockNote rich text editor.
 
-Select some text and click the AI (magic wand) button, or type `/ai` anywhere in the editor to access AI functionality.
+Select some text and click the AI (stars) button, or type `/ai` anywhere in the editor to access AI functionality.
 
 **Relevant Docs:**
 
-- [Editor Setup](/docs/editor-basics/setup)
+- [Getting Stared with BlockNote AI](/docs/ai/getting-started)
 - [Changing the Formatting Toolbar](/docs/ui-components/formatting-toolbar#changing-the-formatting-toolbar)
 - [Changing Slash Menu Items](/docs/ui-components/suggestion-menus#changing-slash-menu-items)
-- [Getting Stared with BlockNote AI](/docs/ai/setup)
diff --git a/examples/09-ai/02-playground/README.md b/examples/09-ai/02-playground/README.md
@@ -6,7 +6,7 @@ Change the configuration, the highlight some text to access the AI menu, or type
 
 **Relevant Docs:**
 
-- [Editor Setup](/docs/editor-basics/setup)
+- [Getting Stared with BlockNote AI](/docs/ai/getting-started)
+- [BlockNote AI Reference](/docs/ai/reference)
 - [Changing the Formatting Toolbar](/docs/ui-components/formatting-toolbar#changing-the-formatting-toolbar)
 - [Changing Slash Menu Items](/docs/ui-components/suggestion-menus#changing-slash-menu-items)
-- [Getting Stared with BlockNote AI](/docs/ai/setup)
diff --git a/examples/09-ai/03-custom-ai-menu-items/README.md b/examples/09-ai/03-custom-ai-menu-items/README.md
@@ -1,10 +1,10 @@
 # Adding AI Menu Items
 
-In this example, we add two items to the AI Menu. The first prompts the AI to make the selected text more casual, and can be found by selecting some text and click the AI (magic wand) button. The second prompts the AI to give ideas on related topics to extend the document with, and can be found by clicking the "Ask AI" Slash Menu item.
+In this example, we add two items to the AI Menu. The first prompts the AI to make the selected text more casual, and can be found by selecting some text and click the AI (stars) button. The second prompts the AI to give ideas on related topics to extend the document with, and can be found by clicking the "Ask AI" Slash Menu item.
 
-Select some text and click the AI (magic wand) button, or type `/ai` anywhere in the editor to access AI functionality.
+Select some text and click the AI (stars) button, or type `/ai` anywhere in the editor to access AI functionality.
 
 **Relevant Docs:**
 
-- [Getting Stared with BlockNote AI](/docs/ai/setup)
+- [Getting Stared with BlockNote AI](/docs/ai/getting-started)
 - [Custom AI Menu Items](/docs/ai/custom-commands)
diff --git a/packages/xl-ai/src/AIExtension.ts b/packages/xl-ai/src/AIExtension.ts
@@ -35,8 +35,8 @@ type AIPluginState = {
   aiMenuState:
     | ({
         /**
-         * The ID of the block that the AI menu is open at
-         * this changes as the AI is making changes to the document
+         * The ID of the block that the AI menu is opened at.
+         * This changes as the AI is making changes to the document
          */
         blockId: string;
       } & (
@@ -64,20 +64,20 @@ type GlobalLLMRequestOptions = {
    * The default language model to use for LLM calls
    */
   model: LanguageModel;
+  /**
+   * Whether to stream the LLM response
+   * @default true
+   */
+  stream?: boolean;
   /**
    * The default data format to use for LLM calls
    * html format is recommended, the other formats are experimental
    * @default llmFormats.html
    */
   dataFormat?: LLMFormat;
-  /**
-   * Whether to stream the LLM response
-   * @default true
-   */
-  stream?: boolean;
   /**
    * A function that can be used to customize the prompt sent to the LLM
-   * @default undefined
+   * @default the default prompt builder for the selected {@link dataFormat}
    */
   promptBuilder?: PromptBuilder;
 };

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "setup": "Editor Setup",`
`3`		`- "custom-commands": "Customizing Commands",`
	`2`	`+ "getting-started": "Getting Started",`
	`3`	`+ "custom-commands": "Custom Commands",`
`4`	`4`	`"reference": "Reference"`
`5`	`5`	`}`