Documentation Demos (#120)

* Added new text cursor fields & functions docs

* Made website and JS docs have same information + minor changes/fixes

* More minor changes & fixes

* More minor changes & fixes

* Added block structure diagram

* remove margin from editor (this is now built-in)

* Added PR feedback and cleaned up links

* Added most live examples

* Cleaned up event listeners

* Made `BNUpdateBlock` also apply props to `blockContainer` node

* Added text cursor demo and fixed listeners for others

* Fixed build error

* Fixed build error

---------

Co-authored-by: yousefed <[email protected]>

Author: matthewlipski

examples/editor/src/App.tsx

@@ -7,7 +7,7 @@ type WindowWithProseMirror = Window & typeof globalThis & { ProseMirror: any };
 
 function App() {
   const editor = useBlockNote({
-    onUpdate: (editor) => {
+    onEditorContentChange: (editor) => {
       console.log(editor.topLevelBlocks);
     },
     editorDOMAttributes: {

examples/vanilla/src/main.tsx

@@ -17,7 +17,7 @@ const editor = new BlockNoteEditor({
     // Create an example menu for when a block is hovered
     blockSideMenuFactory,
   },
-  onUpdate: () => {
+  onEditorContentChange: () => {
     console.log(editor.topLevelBlocks);
   },
   editorDOMAttributes: {

packages/core/src/BlockNoteEditor.ts

@@ -38,8 +38,9 @@ export type BlockNoteEditorOptions = {
   slashCommands: BaseSlashMenuItem[];
   parentElement: HTMLElement;
   editorDOMAttributes: Record<string, string>;
-  onUpdate: (editor: BlockNoteEditor) => void;
-  onCreate: (editor: BlockNoteEditor) => void;
+  onEditorCreate: (editor: BlockNoteEditor) => void;
+  onEditorContentChange: (editor: BlockNoteEditor) => void;
+  onTextCursorPositionChange: (editor: BlockNoteEditor) => void;
 
   // tiptap options, undocumented
   _tiptapOptions: any;
@@ -73,11 +74,14 @@ export class BlockNoteEditor {
     const tiptapOptions: EditorOptions = {
       ...blockNoteTipTapOptions,
       ...options._tiptapOptions,
+      onCreate: () => {
+        options.onEditorCreate?.(this);
+      },
       onUpdate: () => {
-        options.onUpdate?.(this);
+        options.onEditorContentChange?.(this);
       },
-      onCreate: () => {
-        options.onCreate?.(this);
+      onSelectionUpdate: () => {
+        options.onTextCursorPositionChange?.(this);
       },
       extensions:
         options.enableBlockNoteExtensions === false
@@ -291,14 +295,6 @@ export class BlockNoteEditor {
     replaceBlocks(blocksToRemove, blocksToInsert, this._tiptapEditor);
   }
 
-  /**
-   * Executes a callback function whenever the editor's content changes.
-   * @param callback The callback function to execute.
-   */
-  public onContentChange(callback: () => void) {
-    this._tiptapEditor.on("update", callback);
-  }
-
   /**
    * Serializes blocks into an HTML string. To better conform to HTML standards, children of blocks which aren't list
    * items are un-nested in the output HTML.

packages/core/src/extensions/Blocks/nodes/BlockContainer.ts

@@ -187,7 +187,7 @@ export const BlockContainer = Node.create<IBlock>({
               );
             }
 
-            // Changes the block type and adds the provided props as node attributes. Also preserves all existing node
+            // Changes the blockContent node type and adds the provided props as attributes. Also preserves all existing
             // attributes that are compatible with the new type.
             state.tr.setNodeMarkup(
               startPos,
@@ -199,6 +199,13 @@ export const BlockContainer = Node.create<IBlock>({
                 ...block.props,
               }
             );
+
+            // Adds all provided props as attributes to the parent blockContainer node too, and also preserves existing
+            // attributes.
+            state.tr.setNodeMarkup(startPos - 1, undefined, {
+              ...node.attrs,
+              ...block.props,
+            });
           }
 
           return true;

packages/website/docs/docs/blocks.md

@@ -59,32 +59,33 @@ type Block = {
 
 Now that we know how blocks are represented in code, let's take a look at the live example below. We have a BlockNote editor, under which we display its contents using an array of `Block` objects. Feel free to play around and get a better feel for how blocks look in the editor, compared to how they're represented using `Block` objects.
 
-**TODO** Live example.
-
 ::: sandbox {template=react-ts}
 
 ```typescript /App.tsx
 import { useState } from "react";
+import { BlockNoteEditor } from "@blocknote/core";
 import { BlockNoteView, useBlockNote } from "@blocknote/react";
 import "@blocknote/core/style.css";
-import "./styles.css";
 
 export default function App() {
-  const [editorAPI, setEditorAPI] = useState(null);
-  const [blocks, setBlocks] = useState(null);
-
+  // Stores the editor's contents as an array of Block objects.
+  const [blocks, setBlocks] = useState<Block[] | null>(null);
+  
   // Creates a new editor instance.
-  const editor = useBlockNote({});
-
-  // Saves the editor's contents as Block objects.
-  editor.onContentChange(() => setBlocks(editor.allBlocks));
-
-  // Renders the editor instance using a React component.
+  const editor: BlockNoteEditor | null = useBlockNote({
+    // Listens for when the editor's contents change.
+    onEditorContentChange: (editor: BlockNoteEditor) => 
+      // Converts the editor's contents to an array of Block objects.
+      setBlocks(editor.topLevelBlocks)
+  })
+  
+  // Renders a BlockNote editor, and its contents as an array of Block objects 
+  // below.
   return (
-    <>
-      <BlockNoteView editor={editor} />
-      <div>{blocks}</div>
-    </>
+    <div>
+      <BlockNoteView editor={editor}/>
+      <pre>{JSON.stringify(blocks, null, 2)}</pre>
+    </div>
   );
 }
 ```

packages/website/docs/docs/converting-blocks.md

@@ -32,9 +32,46 @@ const HTMLFromBlocks = editor.blocksToHTML(blocks);
 
 To better conform to HTML standards, children of blocks which aren't list items are un-nested in the output HTML.
 
-**Example**
+**Demo**
+
+::: sandbox {template=react-ts}
+
+```typescript /App.tsx
+import { useState } from "react";
+import { BlockNoteEditor } from "@blocknote/core";
+import { BlockNoteView, useBlockNote } from "@blocknote/react";
+import "@blocknote/core/style.css";
+
+export default function App() {
+  // Stores the editor's contents as HTML.
+  const [html, setHTML] = useState<string | null>(null);
+
+  // Creates a new editor instance.
+  const editor = useBlockNote({
+    // Listens for when the editor's contents change.
+    onEditorContentChange: (editor: BlockNoteEditor) => {
+      // Converts the editor's contents from Block objects to HTML and saves 
+      // them.
+      const saveBlocksAsHTML = async () => {
+        const html = await editor.blocksToHTML(editor.topLevelBlocks);
+        setHTML(html);
+      };
+      saveBlocksAsHTML();
+    }
+  });
+
+  // Renders a BlockNote editor, and its contents as HTML below.
+  return (
+    <div>
+      <BlockNoteView editor={editor} />
+      <pre style={{ whiteSpace: "pre-wrap" }}>{html}</pre>
+    </div>
+  );
+}
+```
 
-TODO
+
+:::
 
 ### Converting HTML to Blocks
 
@@ -56,9 +93,56 @@ const blocksFromHTML = editor.HTMLToBlocks(html);
 
 Tries to create `Block` objects out of any HTML block-level elements, and `InlineNode` objects from any HTML inline elements, though not all HTML tags are recognized. If BlockNote doesn't recognize an element's tag, it will parse it as a paragraph or plain text.
 
-**Example**
+**Demo**
+
+::: sandbox {template=react-ts}
+
+```typescript /App.tsx
+import { useEffect, useState } from "react";
+import { BlockNoteEditor } from "@blocknote/core";
+import { BlockNoteView, useBlockNote } from "@blocknote/react";
+import "@blocknote/core/style.css";
+
+export default function App() {
+  // Creates a new editor instance.
+  const editor: BlockNoteEditor | null = useBlockNote({
+    // Makes the editor non-editable.
+    _tiptapOptions: {
+      editable: false,
+    },
+  })
+
+  // Stores the current HTML content.
+  const [html, setHTML] = useState<string>("");
+
+  useEffect(() => {
+    if (editor) {
+      // Whenever the current HTML content changes, converts it to an array of 
+      // Block objects and replaces the editor's content with them.
+      const getBlocks = async () => {
+        const blocks = await editor.HTMLToBlocks(html);
+        editor.replaceBlocks(editor.topLevelBlocks, blocks);
+      };
+      getBlocks();
+    }
+  }, [editor, html]);
+
+  // Renders a text area for you to write/paste HTML in and a BlockNote editor 
+  // below, which displays the current HTML as blocks.
+  return (
+    <div>
+      <textarea
+        style={{ width: "100%", height: "100px" }}
+        value={html}
+        onChange={(event) => setHTML(event.target.value)}
+      />
+      <BlockNoteView editor={editor} />
+    </div>
+  );
+}
+```
 
-TODO
+:::
 
 ## Markdown
 
@@ -84,9 +168,45 @@ const markdownFromBlocks = editor.blocksToMarkdown(blocks);
 
 The output is simplified as Markdown does not support all features of BlockNote - children of blocks which aren't list items are un-nested and certain styles are removed.
 
-**Example**
+**Demo**
+
+::: sandbox {template=react-ts}
+
+```typescript /App.tsx
+import { useState } from "react";
+import { BlockNoteEditor } from "@blocknote/core";
+import { BlockNoteView, useBlockNote } from "@blocknote/react";
+import "@blocknote/core/style.css";
+
+export default function App() {
+  // Stores the editor's contents as Markdown.
+  const [markdown, setMarkdown] = useState<string | null>(null);
+
+  // Creates a new editor instance.
+  const editor = useBlockNote({
+    // Listens for when the editor's contents change.
+    onEditorContentChange: (editor: BlockNoteEditor) => {
+      // Converts the editor's contents from Block objects to Markdown and 
+      // saves them.
+      const saveBlocksAsMarkdown = async () => {
+        const markdown = await editor.blocksToMarkdown(editor.topLevelBlocks);
+        setMarkdown(markdown);
+      };
+      saveBlocksAsMarkdown();
+    }
+  });
+  
+  // Renders a BlockNote editor, and its contents as Markdown below.
+  return (
+    <div>
+      <BlockNoteView editor={editor} />
+      <pre style={{ whiteSpace: "pre-wrap" }}>{markdown}</pre>
+    </div>
+  );
+}
+```
 
-TODO
+:::
 
 ### Converting Markdown to Blocks
 
@@ -108,6 +228,53 @@ const blocksFromMarkdown = editor.markdownToBlocks(markdown);
 
 Tries to create `Block` and `InlineNode` objects based on Markdown syntax, though not all symbols are recognized. If BlockNote doesn't recognize a symbol, it will parse it as text.
 
-**Example**
+**Demo**
+
+::: sandbox {template=react-ts}
+
+```typescript /App.tsx
+import { useEffect, useState } from "react";
+import { BlockNoteEditor } from "@blocknote/core";
+import { BlockNoteView, useBlockNote } from "@blocknote/react";
+import "@blocknote/core/style.css";
+
+export default function App() {
+  // Creates a new editor instance.
+  const editor: BlockNoteEditor | null = useBlockNote({
+    // Makes the editor non-editable.
+    _tiptapOptions: {
+      editable: false,
+    },
+  })
+
+  // Stores the current Markdown content.
+  const [markdown, setMarkdown] = useState<string>("");
+
+  useEffect(() => {
+    if (editor) {
+      // Whenever the current Markdown content changes, converts it to an array
+      // of Block objects and replaces the editor's content with them.
+      const getBlocks = async () => {
+        const blocks = await editor.markdownToBlocks(markdown);
+        editor.replaceBlocks(editor.topLevelBlocks, blocks);
+      };
+      getBlocks();
+    }
+  }, [editor, markdown]);
+
+  // Renders a text area for you to write/paste Markdown in and a BlockNote
+  // editor below, which displays the current Markdown as blocks.
+  return (
+    <div>
+      <textarea
+        style={{ width: "100%", height: "100px" }}
+        value={markdown}
+        onChange={(event) => setMarkdown(event.target.value)}
+      />
+      <BlockNoteView editor={editor} />
+    </div>
+  );
+}
+```
 
-TODO
+:::