Listener Documentation & Section Naming (#126)

* Updated listener docs

* Fixed section naming consistency

* Changed `onEditorCreate` to `onEditorReady`

Author: matthewlipski

packages/core/src/BlockNoteEditor.ts

@@ -38,7 +38,7 @@ export type BlockNoteEditorOptions = {
   slashCommands: BaseSlashMenuItem[];
   parentElement: HTMLElement;
   editorDOMAttributes: Record<string, string>;
-  onEditorCreate: (editor: BlockNoteEditor) => void;
+  onEditorReady: (editor: BlockNoteEditor) => void;
   onEditorContentChange: (editor: BlockNoteEditor) => void;
   onTextCursorPositionChange: (editor: BlockNoteEditor) => void;
 
@@ -75,7 +75,7 @@ export class BlockNoteEditor {
       ...blockNoteTipTapOptions,
       ...options._tiptapOptions,
       onCreate: () => {
-        options.onEditorCreate?.(this);
+        options.onEditorReady?.(this);
       },
       onUpdate: () => {
         options.onEditorContentChange?.(this);

packages/website/docs/.vitepress/config.ts

@@ -22,22 +22,22 @@ const SIDEBAR_DEFAULT = [
     text: "Editor setup",
     collapsed: false,
     items: [
-      { text: "Customizing the editor", link: "/docs/editor" },
-      { text: "Slash menu", link: "/docs/slash-menu" },
-      { text: "Formatting toolbar", link: "/docs/formatting-toolbar" },
-      { text: "Side menu", link: "/docs/side-menu" },
+      { text: "Customizing the Editor", link: "/docs/editor" },
+      { text: "Slash Menu", link: "/docs/slash-menu" },
+      { text: "Formatting Toolbar", link: "/docs/formatting-toolbar" },
+      { text: "Side Menu", link: "/docs/side-menu" },
     ],
   },
   {
     text: "Working with Blocks",
     collapsed: false,
     items: [
       { text: "Introduction to Blocks", link: "/docs/blocks" },
-      { text: "Block types", link: "/docs/block-types" },
+      { text: "Block Types & Properties", link: "/docs/block-types" },
       { text: "Manipulating Blocks", link: "/docs/manipulating-blocks" },
       { text: "Inline Content", link: "/docs/inline-content" },
-      { text: "Cursor and selections", link: "/docs/cursor-selections" },
-      { text: "Markdown and HTML", link: "/docs/converting-blocks" },
+      { text: "Cursor & Selections", link: "/docs/cursor-selections" },
+      { text: "Markdown & HTML", link: "/docs/converting-blocks" },
     ],
   },
 

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

@@ -1,36 +1,36 @@
-# Converting Blocks to and from other formats
+# Markdown & HTML
 
-It's possible to export Blocks to other formats, or import Blocks from other formats.
+It's possible to export or import Blocks to and from Markdown and HTML.
 
 ::: warning
-The functions to import / export to and from HTML / Markdown are considered "lossy"; some information might be dropped when you export Blocks to those formats.
+The functions to import/export to and from Markdown/HTML are considered "lossy"; some information might be dropped when you export Blocks to those formats.
 
 To serialize Blocks to a non-lossy format (for example, to store the contents of the editor in your backend), simply export the built-in Block format using `JSON.stringify(editor.allBlocks)`.
 :::
 
-## HTML
+## Markdown
 
-We expose functions to convert Blocks to and from HTML. Converting Blocks to HTML will lose some information such as the nesting of nodes in order to export a simple HTML structure.
+BlockNote can import / export Blocks to and from Markdown. Note that this is also considered "lossy", as not all structures can be entirely represented in Markdown.
 
-### Converting Blocks to HTML
+### Converting Blocks to Markdown
 
-`Block` objects can be serialized to an HTML string using the following function:
+`Block` objects can be serialized to a Markdown string using the following function:
 
 ```typescript
 // Definition
 class BlockNoteEditor {
 ...
-  public blocksToHTML(blocks: Block[]): string;
+  public blocksToMarkdown(blocks: Block[]): string;
 ...
 }
 
 // Usage
-const HTMLFromBlocks = editor.blocksToHTML(blocks);
+const markdownFromBlocks = editor.blocksToMarkdown(blocks);
 ```
 
-`returns:` The blocks, serialized as an HTML string.
+`returns:` The blocks, serialized as a Markdown string.
 
-To better conform to HTML standards, children of blocks which aren't list items are un-nested in the output HTML.
+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.
 
 **Demo**
 
@@ -43,55 +43,54 @@ 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);
+  // 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 HTML and saves 
-      // them.
-      const saveBlocksAsHTML = async () => {
-        const html = await editor.blocksToHTML(editor.topLevelBlocks);
-        setHTML(html);
+      // 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);
       };
-      saveBlocksAsHTML();
+      saveBlocksAsMarkdown();
     }
   });
-
-  // Renders a BlockNote editor, and its contents as HTML below.
+  
+  // Renders a BlockNote editor, and its contents as Markdown below.
   return (
     <div>
       <BlockNoteView editor={editor} />
-      <pre style={{ whiteSpace: "pre-wrap" }}>{html}</pre>
+      <pre style={{ whiteSpace: "pre-wrap" }}>{markdown}</pre>
     </div>
   );
 }
 ```
 
-
 :::
 
-### Converting HTML to Blocks
+### Converting Markdown to Blocks
 
-`Block` objects can be parsed from an HTML string using the following function:
+`Block` objects can be parsed from a Markdown string using the following function:
 
 ```typescript
 // Definition
 class BlockNoteEditor {
 ...
-  public HTMLToBlocks(html: string): Blocks[];
+  public markdownToBlocks(markdown: string): Blocks[];
 ...
 }
 
 // Usage
-const blocksFromHTML = editor.HTMLToBlocks(html);
+const blocksFromMarkdown = editor.markdownToBlocks(markdown);
 ```
 
-`returns:` The blocks parsed from the HTML string.
+`returns:` The blocks parsed from the Markdown string.
 
-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.
+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.
 
 **Demo**
 
@@ -112,29 +111,29 @@ export default function App() {
     },
   })
 
-  // Stores the current HTML content.
-  const [html, setHTML] = useState<string>("");
+  // Stores the current Markdown content.
+  const [markdown, setMarkdown] = 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.
+      // 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.HTMLToBlocks(html);
+        const blocks = await editor.markdownToBlocks(markdown);
         editor.replaceBlocks(editor.topLevelBlocks, blocks);
       };
       getBlocks();
     }
-  }, [editor, html]);
+  }, [editor, markdown]);
 
-  // Renders a text area for you to write/paste HTML in and a BlockNote editor 
-  // below, which displays the current HTML as blocks.
+  // 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={html}
-        onChange={(event) => setHTML(event.target.value)}
+        value={markdown}
+        onChange={(event) => setMarkdown(event.target.value)}
       />
       <BlockNoteView editor={editor} />
     </div>
@@ -144,29 +143,29 @@ export default function App() {
 
 :::
 
-## Markdown
+## HTML
 
-BlockNote can import / export Blocks to and from Markdown. Note that this is also considered "lossy", as not all structures can be entirely represented in Markdown.
+We expose functions to convert Blocks to and from HTML. Converting Blocks to HTML will lose some information such as the nesting of nodes in order to export a simple HTML structure.
 
-### Converting Blocks to Markdown
+### Converting Blocks to HTML
 
-`Block` objects can be serialized to a Markdown string using the following function:
+`Block` objects can be serialized to an HTML string using the following function:
 
 ```typescript
 // Definition
 class BlockNoteEditor {
 ...
-  public blocksToMarkdown(blocks: Block[]): string;
+  public blocksToHTML(blocks: Block[]): string;
 ...
 }
 
 // Usage
-const markdownFromBlocks = editor.blocksToMarkdown(blocks);
+const HTMLFromBlocks = editor.blocksToHTML(blocks);
 ```
 
-`returns:` The blocks, serialized as a Markdown string.
+`returns:` The blocks, serialized as an HTML string.
 
-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.
+To better conform to HTML standards, children of blocks which aren't list items are un-nested in the output HTML.
 
 **Demo**
 
@@ -179,54 +178,54 @@ 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);
+  // 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 Markdown and 
-      // saves them.
-      const saveBlocksAsMarkdown = async () => {
-        const markdown = await editor.blocksToMarkdown(editor.topLevelBlocks);
-        setMarkdown(markdown);
+      // 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);
       };
-      saveBlocksAsMarkdown();
+      saveBlocksAsHTML();
     }
   });
-  
-  // Renders a BlockNote editor, and its contents as Markdown below.
+
+  // Renders a BlockNote editor, and its contents as HTML below.
   return (
     <div>
       <BlockNoteView editor={editor} />
-      <pre style={{ whiteSpace: "pre-wrap" }}>{markdown}</pre>
+      <pre style={{ whiteSpace: "pre-wrap" }}>{html}</pre>
     </div>
   );
 }
 ```
 
 :::
 
-### Converting Markdown to Blocks
+### Converting HTML to Blocks
 
-`Block` objects can be parsed from a Markdown string using the following function:
+`Block` objects can be parsed from an HTML string using the following function:
 
 ```typescript
 // Definition
 class BlockNoteEditor {
 ...
-  public markdownToBlocks(markdown: string): Blocks[];
+  public HTMLToBlocks(html: string): Blocks[];
 ...
 }
 
 // Usage
-const blocksFromMarkdown = editor.markdownToBlocks(markdown);
+const blocksFromHTML = editor.HTMLToBlocks(html);
 ```
 
-`returns:` The blocks parsed from the Markdown string.
+`returns:` The blocks parsed from the HTML string.
 
-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.
+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.
 
 **Demo**
 
@@ -247,34 +246,34 @@ export default function App() {
     },
   })
 
-  // Stores the current Markdown content.
-  const [markdown, setMarkdown] = useState<string>("");
+  // Stores the current HTML content.
+  const [html, setHTML] = 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.
+      // 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.markdownToBlocks(markdown);
+        const blocks = await editor.HTMLToBlocks(html);
         editor.replaceBlocks(editor.topLevelBlocks, blocks);
       };
       getBlocks();
     }
-  }, [editor, markdown]);
+  }, [editor, html]);
 
-  // Renders a text area for you to write/paste Markdown in and a BlockNote
-  // editor below, which displays the current Markdown as blocks.
+  // 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={markdown}
-        onChange={(event) => setMarkdown(event.target.value)}
+        value={html}
+        onChange={(event) => setHTML(event.target.value)}
       />
       <BlockNoteView editor={editor} />
     </div>
   );
 }
 ```
 
-:::
+:::

packages/website/docs/docs/cursor-selections.md

@@ -1,18 +1,14 @@
-# Cursor and Selections
+# Cursor & Selections
 
-This page will explain how to work with the Cursor and Selections
-
-- explain differences
-- how to get / set them
-- examples (how to get)
+If you want to know which block(s) the user is currently editing, you can do so using cursor positions and selections.
 
 ## Cursor Positions
 
-BlockNote allows you to keep track of the text cursor position in the editor, to get information about the block it's in and its surrounding blocks.
+BlockNote keeps track of the text cursor position in the editor and exposes functions that let you retrieve it or change it.
 
 ## Text Cursor
 
-The text cursor is the blinking vertical line you see when typing in the editor. In code, its position is represented using the following object:
+The text cursor is the blinking vertical line you see when typing in the editor. BlockNote uses `TextCursorPosition` objects to give you information about the block it's in as well as those around it:
 
 ```typescript
 type TextCursorPosition = {