docs: Ordered editor options alphabetically and updated docs (#1471)

Author: matthewlipski

docs/pages/docs/editor-basics/setup.mdx

@@ -19,39 +19,62 @@ function useCreateBlockNote(
 ): BlockNoteEditor;
 
 type BlockNoteEditorOptions = {
-  initialContent?: PartialBlock[];
-  domAttributes?: Record<string, string>;
-  defaultStyles?: boolean;
-  uploadFile?: (file: File) => Promise<string>;
+  animations?: boolean;
   collaboration?: CollaborationOptions;
+  defaultStyles?: boolean;
   dictionary?: Dictionary;
+  disableExtensions?: string[];
+  domAttributes?: Record<string, string>;
+  dropCursor?: (opts: {
+    editor: BlockNoteEditor;
+    color?: string | false;
+    width?: number;
+    class?: string;
+  }) => Plugin;
+  initialContent?: PartialBlock[];
+  resolveFileUrl: (url: string) => Promise<string>
   schema?: BlockNoteSchema;
+  setIdAttribute?: boolean;
+  sideMenuDetection?: "viewport" | "editor";
+  tabBehavior?: "prefer-navigate-ui" | "prefer-indent"
   trailingBlock?: boolean;
-  animations?: boolean;
+  uploadFile?: (file: File) => Promise<string>;
 };
 ```
 
 The hook takes two optional parameters:
 
 **options:** An object containing options for the editor:
 
-`initialContent:` The content that should be in the editor when it's created, represented as an array of [partial block objects](/docs/manipulating-blocks#partial-blocks).
+`animations`: Whether changes to blocks (like indentation, creating lists, changing headings) should be animated or not. Defaults to `true`.
 
-`domAttributes:` An object containing HTML attributes that should be added to various DOM elements in the editor. See [Adding DOM Attributes](/docs/theming#adding-dom-attributes) for more.
+`collaboration`: Options for enabling real-time collaboration. See [Real-time Collaboration](/docs/advanced/real-time-collaboration) for more info.
 
 `defaultStyles`: Whether to use the default font and reset the styles of `<p>`, `<li>`, `<h1>`, etc. elements that are used in BlockNote. Defaults to true if undefined.
 
-`uploadFile`: A function which handles file uploads and eventually returns the URL to the uploaded file. Used for [Image blocks](/docs/editor-basics/default-schema#image).
+`dictionary`: Provide strings for localization. See the [Localization / i18n example](/examples/basic/localization) and [Custom Placeholders](/examples/basic/custom-placeholder).
 
-`collaboration`: Options for enabling real-time collaboration. See [Real-time Collaboration](/docs/advanced/real-time-collaboration) for more info.
+`disableExtensions` (_advanced_): Disables TipTap extensions used in BlockNote by default, based on their names.
 
-`dictionary`: Provide strings for localization. See the [Localization / i18n example](/examples/basic/localization) and [Custom Placeholders](/examples/basic/custom-placeholder).
+`domAttributes:` An object containing HTML attributes that should be added to various DOM elements in the editor. See [Adding DOM Attributes](/docs/theming#adding-dom-attributes) for more.
+
+`dropCursor`: A replacement indicator to use when dragging and dropping blocks. Uses the [ProseMirror drop cursor](https://github.com/ProseMirror/prosemirror-dropcursor), or a modified version when [Column Blocks](/docs/editor-basics/document-structure#column-blocks) are enabled.
+
+`initialContent:` The content that should be in the editor when it's created, represented as an array of [Partial Blocks](/docs/manipulating-blocks#partial-blocks).
 
-`schema` (_advanced_): The editor schema if you want to extend your editor with custom blocks, styles, or inline content [Custom Schemas](/docs/custom-schemas).
+`resolveFileUrl:` An async function that fetches the download URL of a file from an initial URL.
+
+`schema`: The editor schema if you want to extend your editor with custom blocks, styles, or inline content [Custom Schemas](/docs/custom-schemas).
+
+`setIdAttribute`: Whether to render an `id` HTML attribute on blocks as well as a `data-id` attribute. Defaults to `false`.
+
+`sideMenuDetection`: Determines whether the mouse cursor position is locked to the editor bounding box for showing the [Block Side Menu](/docs/ui-components/side-menu) and block drag & drop. When set to `viewport`, the Side Menu will be shown next to the nearest block to the cursor, regardless of where it is in the viewport. Dropping blocks will also be locked to the editor bounding box. Otherwise, the Side Menu will only be shown when the cursor is within the editor bounds, and blocks can only be dropped when hovering the editor. In order to use multiple editors, must be set to `editor`. Defaults to `viewport`.
+
+`tabBehavior`: Determines whether pressing the tab key should navigate the UI for keyboard accessibility or indent the current block. Defaults to `prefer-navigate-ui`.
 
 `trailingBlock`: An option which user can pass with `false` value to disable the automatic creation of a trailing new block on the next line when the user types or edits any block. Defaults to `true` if undefined.
 
-`animations`: Whether changes to blocks (like indentation, creating lists, changing headings) should be animated or not. Defaults to `true`.
+`uploadFile`: A function which handles file uploads and eventually returns the URL to the uploaded file. Used for [Image blocks](/docs/editor-basics/default-schema#image).
 
 **deps:** Dependency array that's internally passed to `useMemo`. A new editor will only be created when this array changes.
 

packages/core/src/editor/BlockNoteEditor.ts

@@ -117,69 +117,6 @@ export type BlockNoteEditorOptions<
    */
   animations?: boolean;
 
-  /**
-   * Disable internal extensions (based on keys / extension name)
-   */
-  disableExtensions: string[];
-
-  /**
-   * A dictionary object containing translations for the editor.
-   */
-  dictionary?: Dictionary & Record<string, any>;
-
-  /**
-   * @deprecated, provide placeholders via dictionary instead
-   */
-  placeholders: Record<
-    string | "default" | "emptyDocument",
-    string | undefined
-  >;
-
-  /**
-   * An object containing attributes that should be added to HTML elements of the editor.
-   *
-   * @example { editor: { class: "my-editor-class" } }
-   */
-  domAttributes: Partial<BlockNoteDOMAttributes>;
-
-  /**
-   * The content that should be in the editor when it's created, represented as an array of partial block objects.
-   */
-  initialContent: PartialBlock<
-    NoInfer<BSchema>,
-    NoInfer<ISchema>,
-    NoInfer<SSchema>
-  >[];
-  /**
-   * Use default BlockNote font and reset the styles of <p> <li> <h1> elements etc., that are used in BlockNote.
-   *
-   * @default true
-   */
-  defaultStyles: boolean;
-
-  schema: BlockNoteSchema<BSchema, ISchema, SSchema>;
-
-  /**
-   * The `uploadFile` method is what the editor uses when files need to be uploaded (for example when selecting an image to upload).
-   * This method should set when creating the editor as this is application-specific.
-   *
-   * `undefined` means the application doesn't support file uploads.
-   *
-   * @param file The file that should be uploaded.
-   * @returns The URL of the uploaded file OR an object containing props that should be set on the file block (such as an id)
-   */
-  uploadFile: (
-    file: File,
-    blockId?: string
-  ) => Promise<string | Record<string, any>>;
-
-  /**
-   * Resolve a URL of a file block to one that can be displayed or downloaded. This can be used for creating authenticated URL or
-   * implementing custom protocols / schemes
-   * @returns The URL that's
-   */
-  resolveFileUrl: (url: string) => Promise<string>;
-
   /**
    * When enabled, allows for collaboration between multiple users.
    */
@@ -213,25 +150,65 @@ export type BlockNoteEditorOptions<
   };
 
   /**
-   * additional tiptap options, undocumented
+   * Use default BlockNote font and reset the styles of <p> <li> <h1> elements etc., that are used in BlockNote.
+   *
+   * @default true
    */
-  _tiptapOptions: Partial<EditorOptions>;
+  defaultStyles: boolean;
 
   /**
-   * (experimental) add extra prosemirror plugins or tiptap extensions to the editor
+   * A dictionary object containing translations for the editor.
    */
-  _extensions: Record<string, BlockNoteExtension | BlockNoteExtensionFactory>;
+  dictionary?: Dictionary & Record<string, any>;
 
-  trailingBlock?: boolean;
+  /**
+   * Disable internal extensions (based on keys / extension name)
+   */
+  disableExtensions: string[];
 
   /**
-   * Boolean indicating whether the editor is in headless mode.
-   * Headless mode means we can use features like importing / exporting blocks,
-   * but there's no underlying editor (UI) instantiated.
+   * An object containing attributes that should be added to HTML elements of the editor.
    *
-   * You probably don't need to set this manually, but use the `server-util` package instead that uses this option internally
+   * @example { editor: { class: "my-editor-class" } }
    */
-  _headless: boolean;
+  domAttributes: Partial<BlockNoteDOMAttributes>;
+
+  dropCursor?: (opts: {
+    editor: BlockNoteEditor<
+      NoInfer<BSchema>,
+      NoInfer<ISchema>,
+      NoInfer<SSchema>
+    >;
+    color?: string | false;
+    width?: number;
+    class?: string;
+  }) => Plugin;
+
+  /**
+   * The content that should be in the editor when it's created, represented as an array of partial block objects.
+   */
+  initialContent: PartialBlock<
+    NoInfer<BSchema>,
+    NoInfer<ISchema>,
+    NoInfer<SSchema>
+  >[];
+
+  /**
+   * @deprecated, provide placeholders via dictionary instead
+   */
+  placeholders: Record<
+    string | "default" | "emptyDocument",
+    string | undefined
+  >;
+
+  /**
+   * Resolve a URL of a file block to one that can be displayed or downloaded. This can be used for creating authenticated URL or
+   * implementing custom protocols / schemes
+   * @returns The URL that's
+   */
+  resolveFileUrl: (url: string) => Promise<string>;
+
+  schema: BlockNoteSchema<BSchema, ISchema, SSchema>;
 
   /**
    * A flag indicating whether to set an HTML ID for every block
@@ -243,7 +220,14 @@ export type BlockNoteEditorOptions<
    */
   setIdAttribute?: boolean;
 
-  dropCursor?: (opts: any) => Plugin;
+  /**
+   * The detection mode for showing the side menu - "viewport" always shows the
+   * side menu for the block next to the mouse cursor, while "editor" only shows
+   * it when hovering the editor or the side menu itself.
+   *
+   * @default "viewport"
+   */
+  sideMenuDetection: "viewport" | "editor";
 
   /**
    Select desired behavior when pressing `Tab` (or `Shift-Tab`). Specifically,
@@ -260,14 +244,40 @@ export type BlockNoteEditorOptions<
    */
   tabBehavior: "prefer-navigate-ui" | "prefer-indent";
 
+  trailingBlock?: boolean;
+
   /**
-   * The detection mode for showing the side menu - "viewport" always shows the
-   * side menu for the block next to the mouse cursor, while "editor" only shows
-   * it when hovering the editor or the side menu itself.
+   * The `uploadFile` method is what the editor uses when files need to be uploaded (for example when selecting an image to upload).
+   * This method should set when creating the editor as this is application-specific.
    *
-   * @default "viewport"
+   * `undefined` means the application doesn't support file uploads.
+   *
+   * @param file The file that should be uploaded.
+   * @returns The URL of the uploaded file OR an object containing props that should be set on the file block (such as an id)
    */
-  sideMenuDetection: "viewport" | "editor";
+  uploadFile: (
+    file: File,
+    blockId?: string
+  ) => Promise<string | Record<string, any>>;
+
+  /**
+   * additional tiptap options, undocumented
+   */
+  _tiptapOptions: Partial<EditorOptions>;
+
+  /**
+   * (experimental) add extra prosemirror plugins or tiptap extensions to the editor
+   */
+  _extensions: Record<string, BlockNoteExtension | BlockNoteExtensionFactory>;
+
+  /**
+   * Boolean indicating whether the editor is in headless mode.
+   * Headless mode means we can use features like importing / exporting blocks,
+   * but there's no underlying editor (UI) instantiated.
+   *
+   * You probably don't need to set this manually, but use the `server-util` package instead that uses this option internally
+   */
+  _headless: boolean;
 };
 
 const blockNoteTipTapOptions = {