docs: add docs for yjs utils

Author: nperez0111

docs/content/docs/reference/editor/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Editor",
-  "pages": ["overview", "manipulating-content", "cursor-selections", "..."]
+  "pages": ["overview", "manipulating-content", "cursor-selections", "yjs-utilities", "..."]
 }

docs/content/docs/reference/editor/overview.mdx

@@ -118,6 +118,12 @@ The editor can be configured with the following options when using `BlockNoteEdi
   name="BlockNoteEditorOptions"
 />
 
+## YJS Utilities
+
+BlockNote provides utilities for working with YJS collaborative documents. These utilities allow you to convert between BlockNote blocks and YJS documents programmatically.
+
+To read more about YJS utilities, see the [YJS Utilities](/docs/reference/editor/yjs-utilities) reference.
+
 ## Related Documentation
 
 For more detailed information about specific areas:

docs/content/docs/reference/editor/yjs-utilities.mdx

@@ -0,0 +1,350 @@
+---
+title: YJS Utilities
+description: Utilities for converting between BlockNote blocks and YJS collaborative documents
+imageTitle: YJS Utilities
+---
+
+# YJS Utilities
+
+The `@blocknote/core/yjs` export provides utilities for converting between BlockNote blocks and YJS collaborative documents. These utilities are useful when you need to work with YJS documents outside of the standard collaboration setup, such as importing existing content or working with YJS documents programmatically.
+
+## Import
+
+```typescript
+import {
+  blocksToYDoc,
+  blocksToYXmlFragment,
+  yDocToBlocks,
+  yXmlFragmentToBlocks,
+  _blocksToProsemirrorNode,
+  _prosemirrorJSONToBlocks,
+} from "@blocknote/core/yjs";
+```
+
+## Overview
+
+YJS utilities enable bidirectional conversion between:
+
+- **BlockNote blocks** ↔ **Y.Doc** (YJS document)
+- **BlockNote blocks** ↔ **Y.XmlFragment** (YJS XML fragment)
+- **BlockNote blocks** ↔ **Prosemirror nodes** (intermediate format)
+
+These conversions are essential for:
+
+- Importing existing BlockNote content into a YJS document for collaboration
+- Exporting content from a YJS document back to BlockNote blocks
+- Working with YJS documents programmatically without an active editor instance
+
+## Converting Blocks to YJS Documents
+
+### `blocksToYDoc`
+
+Converts BlockNote blocks into a Y.Doc. This is useful when importing existing content to a Y.Doc for the first time.
+
+<Callout type="warning">
+  **Important:** This should not be used to rehydrate a Y.Doc from a database once collaboration has begun, as all history will be lost.
+</Callout>
+
+```typescript
+function blocksToYDoc<
+  BSchema extends BlockSchema,
+  ISchema extends InlineContentSchema,
+  SSchema extends StyleSchema,
+>(
+  editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
+  blocks: PartialBlock<BSchema, ISchema, SSchema>[],
+  xmlFragment?: string
+): Y.Doc
+```
+
+**Parameters:**
+
+- `editor` - The BlockNote editor instance
+- `blocks` - Array of blocks to convert
+- `xmlFragment` - Optional XML fragment name (defaults to `"prosemirror"`)
+
+**Returns:** A new Y.Doc containing the converted blocks
+
+**Example:**
+
+```typescript
+import { BlockNoteEditor } from "@blocknote/core";
+import { blocksToYDoc } from "@blocknote/core/yjs";
+import * as Y from "yjs";
+
+const editor = BlockNoteEditor.create();
+
+const blocks = [
+  {
+    type: "paragraph",
+    content: "Hello, world!",
+  },
+  {
+    type: "heading",
+    props: { level: 1 },
+    content: "My Document",
+  },
+];
+
+// Convert blocks to Y.Doc
+const ydoc = blocksToYDoc(editor, blocks);
+
+// Now you can use this Y.Doc with a YJS provider for collaboration
+const provider = new WebrtcProvider("my-room", ydoc);
+```
+
+### `blocksToYXmlFragment`
+
+Converts BlockNote blocks into a Y.XmlFragment. This is useful when you want to work with a specific XML fragment within a Y.Doc.
+
+```typescript
+function blocksToYXmlFragment<
+  BSchema extends BlockSchema,
+  ISchema extends InlineContentSchema,
+  SSchema extends StyleSchema,
+>(
+  editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
+  blocks: Block<BSchema, ISchema, SSchema>[],
+  xmlFragment?: Y.XmlFragment
+): Y.XmlFragment
+```
+
+**Parameters:**
+
+- `editor` - The BlockNote editor instance
+- `blocks` - Array of blocks to convert
+- `xmlFragment` - Optional existing Y.XmlFragment to populate (creates new one if not provided)
+
+**Returns:** A Y.XmlFragment containing the converted blocks
+
+**Example:**
+
+```typescript
+import { BlockNoteEditor } from "@blocknote/core";
+import { blocksToYXmlFragment } from "@blocknote/core/yjs";
+import * as Y from "yjs";
+
+const editor = BlockNoteEditor.create();
+const doc = new Y.Doc();
+const fragment = doc.getXmlFragment("my-fragment");
+
+const blocks = [
+  {
+    type: "paragraph",
+    content: "Content for fragment",
+  },
+];
+
+// Convert blocks to the XML fragment
+blocksToYXmlFragment(editor, blocks, fragment);
+```
+
+## Converting YJS Documents to Blocks
+
+### `yDocToBlocks`
+
+Converts a Y.Doc back into BlockNote blocks. This is useful for reading content from a YJS document.
+
+```typescript
+function yDocToBlocks<
+  BSchema extends BlockSchema,
+  ISchema extends InlineContentSchema,
+  SSchema extends StyleSchema,
+>(
+  editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
+  ydoc: Y.Doc,
+  xmlFragment?: string
+): Block<BSchema, ISchema, SSchema>[]
+```
+
+**Parameters:**
+
+- `editor` - The BlockNote editor instance
+- `ydoc` - The Y.Doc to convert
+- `xmlFragment` - Optional XML fragment name (defaults to `"prosemirror"`)
+
+**Returns:** Array of BlockNote blocks
+
+**Example:**
+
+```typescript
+import { BlockNoteEditor } from "@blocknote/core";
+import { yDocToBlocks } from "@blocknote/core/yjs";
+import * as Y from "yjs";
+
+const editor = BlockNoteEditor.create();
+const ydoc = new Y.Doc();
+
+// ... Y.Doc is populated through collaboration or other means ...
+
+// Convert Y.Doc back to blocks
+const blocks = yDocToBlocks(editor, ydoc);
+
+console.log(blocks); // Array of BlockNote blocks
+```
+
+### `yXmlFragmentToBlocks`
+
+Converts a Y.XmlFragment back into BlockNote blocks.
+
+```typescript
+function yXmlFragmentToBlocks<
+  BSchema extends BlockSchema,
+  ISchema extends InlineContentSchema,
+  SSchema extends StyleSchema,
+>(
+  editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
+  xmlFragment: Y.XmlFragment
+): Block<BSchema, ISchema, SSchema>[]
+```
+
+**Parameters:**
+
+- `editor` - The BlockNote editor instance
+- `xmlFragment` - The Y.XmlFragment to convert
+
+**Returns:** Array of BlockNote blocks
+
+**Example:**
+
+```typescript
+import { BlockNoteEditor } from "@blocknote/core";
+import { yXmlFragmentToBlocks } from "@blocknote/core/yjs";
+import * as Y from "yjs";
+
+const editor = BlockNoteEditor.create();
+const doc = new Y.Doc();
+const fragment = doc.getXmlFragment("my-fragment");
+
+// ... Fragment is populated through collaboration or other means ...
+
+// Convert fragment back to blocks
+const blocks = yXmlFragmentToBlocks(editor, fragment);
+```
+
+## Prosemirror Conversions
+
+### `_blocksToProsemirrorNode`
+
+Converts BlockNote blocks to a Prosemirror node. This is an intermediate conversion step used internally.
+
+```typescript
+function _blocksToProsemirrorNode<
+  BSchema extends BlockSchema,
+  ISchema extends InlineContentSchema,
+  SSchema extends StyleSchema,
+>(
+  editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
+  blocks: PartialBlock<BSchema, ISchema, SSchema>[]
+): Node
+```
+
+**Parameters:**
+
+- `editor` - The BlockNote editor instance
+- `blocks` - Array of blocks to convert
+
+**Returns:** Prosemirror root node
+
+### `_prosemirrorJSONToBlocks`
+
+Converts Prosemirror JSON to BlockNote blocks.
+
+```typescript
+function _prosemirrorJSONToBlocks<
+  BSchema extends BlockSchema,
+  ISchema extends InlineContentSchema,
+  SSchema extends StyleSchema,
+>(
+  editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
+  json: any
+): Block<BSchema, ISchema, SSchema>[]
+```
+
+**Parameters:**
+
+- `editor` - The BlockNote editor instance
+- `json` - Prosemirror JSON object
+
+**Returns:** Array of BlockNote blocks
+
+## Complete Example: Importing Existing Content
+
+Here's a complete example showing how to import existing BlockNote content into a YJS document for collaboration:
+
+```typescript
+import { BlockNoteEditor } from "@blocknote/core";
+import { blocksToYDoc, yDocToBlocks } from "@blocknote/core/yjs";
+import { WebrtcProvider } from "y-webrtc";
+import * as Y from "yjs";
+
+// Create editor
+const editor = BlockNoteEditor.create();
+
+// Existing content you want to import
+const existingBlocks = [
+  {
+    type: "heading",
+    props: { level: 1 },
+    content: "Welcome to Collaboration",
+  },
+  {
+    type: "paragraph",
+    content: "This content will be synced across all users.",
+  },
+];
+
+// Convert blocks to Y.Doc
+const ydoc = blocksToYDoc(editor, existingBlocks);
+
+// Set up collaboration provider
+const provider = new WebrtcProvider("my-room", ydoc);
+
+// Create editor with collaboration
+const collaborativeEditor = BlockNoteEditor.create({
+  collaboration: {
+    provider,
+    fragment: ydoc.getXmlFragment("prosemirror"),
+    user: {
+      name: "User 1",
+      color: "#ff0000",
+    },
+  },
+});
+
+// Later, you can read the content back
+const currentBlocks = yDocToBlocks(editor, ydoc);
+console.log("Current document:", currentBlocks);
+```
+
+## Round-trip Conversion
+
+All conversion functions support round-trip conversion, meaning you can convert blocks → YJS → blocks and get back the same content:
+
+```typescript
+import { BlockNoteEditor } from "@blocknote/core";
+import { blocksToYDoc, yDocToBlocks } from "@blocknote/core/yjs";
+
+const editor = BlockNoteEditor.create();
+
+const originalBlocks = [
+  {
+    type: "paragraph",
+    content: "Test content",
+  },
+];
+
+// Convert to Y.Doc and back
+const ydoc = blocksToYDoc(editor, originalBlocks);
+const convertedBlocks = yDocToBlocks(editor, ydoc);
+
+// originalBlocks and convertedBlocks are equivalent
+console.log(originalBlocks); // Same structure as convertedBlocks
+```
+
+## Related Documentation
+
+- [Real-time Collaboration](/docs/features/collaboration) - Learn how to set up collaboration in BlockNote
+- [Manipulating Content](/docs/reference/editor/manipulating-content) - Working with blocks and inline content
+- [Server Utilities](/docs/reference/server-util) - Server-side utilities for BlockNote (uses these YJS utilities internally)
+