Skip to content

docs: Ordered editor options alphabetically and updated docs #1471

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 28, 2025
Merged

docs: Ordered editor options alphabetically and updated docs #1471

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 35 additions & 12 deletions docs/pages/docs/editor-basics/setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
168 changes: 89 additions & 79 deletions packages/core/src/editor/BlockNoteEditor.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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
Expand All @@ -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,
Expand All @@ -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 = {
Expand Down
Loading