-
-**Type & Props**
-
-```typescript
-type ParagraphBlock = {
- id: string;
- type: "paragraph";
- props: DefaultProps;
- content: InlineContent[];
- children: Block[];
-};
-```
-
-### Heading
-
-**Appearance**
-
-
-
-**Type & Props**
-
-```typescript
-type HeadingBlock = {
- id: string;
- type: "heading";
- props: {
- level: 1 | 2 | 3 = 1;
- } & DefaultProps;
- content: InlineContent[];
- children: Block[];
-};
-```
-
-`level:` The heading level, representing a title (`level: 1`), heading (`level: 2`), and subheading (`level: 3`).
-
-### Bullet List Item
-
-**Appearance**
-
-
-
-**Type & Props**
-
-```typescript
-type BulletListItemBlock = {
- id: string;
- type: "bulletListItem";
- props: DefaultProps;
- content: InlineContent[];
- children: Block[];
-};
-```
-
-### Numbered List Item
-
-**Appearance**
-
-
-
-**Type & Props**
-
-```typescript
-type NumberedListItemBlock = {
- id: string;
- type: "numberedListItem";
- props: DefaultProps;
- content: InlineContent[];
- children: Block[];
-};
-```
-
-### Image
-
-**Appearance**
-
-
-
-**Type & Props**
-
-```typescript
-type ImageBlock = {
- id: string;
- type: "image";
- props: {
- url: string = "";
- caption: string = "";
- width: number = 512;
- } & Omit
-
-**Type & Props**
-
-```typescript
-type TableBlock = {
- id: string;
- type: "table";
- props: DefaultProps;
- content: TableContent[];
- children: Block[];
-};
-```
-
-## Default Block Properties
-
-While each type of block can have its own set of properties, there are some properties that all built-in block types have by default, which you can find in the definition for `DefaultProps`:
-
-```typescript
-type DefaultProps = {
- backgroundColor: string = "default";
- textColor: string = "default";
- textAlignment: "left" | "center" | "right" | "justify" = "left";
-};
-```
-
-`backgroundColor:` The background color of the block, which also applies to nested blocks.
-
-`textColor:` The text color of the block, which also applies to nested blocks.
-
-`textAlignment:` The text alignment of the block.
-
-## Creating your own blocks
-
-You can create your own custom blocks using React. Skip to the Advanced "custom schemas" section to learn more about extending the editor. (TODO: link)
\ No newline at end of file
diff --git a/docs/pages/docs/editor-api/editor.mdx b/docs/pages/docs/editor-api/editor.mdx
deleted file mode 100644
index 5429872d54..0000000000
--- a/docs/pages/docs/editor-api/editor.mdx
+++ /dev/null
@@ -1,76 +0,0 @@
----
-title: Editor Setup
-description: While you can get started with BlockNote in minutes, it's likely that you'll want to customize its features and functionality to better suit your app.
-imageTitle: Customizing the Editor
-path: /docs/editor
----
-
-import { Example } from "@/components/example";
-
-TODO:
-[x] review API
-[x] what needs to be part of useBlockNote vs the component?
-[ ] document instantiation / useBlockNote
-[ ] expose / document hooks
-[ ] document events
-[ ] explain controlled / uncontrolled
-[ ] Maybe move outside of "Editor API"?
-
-# Editor Setup
-
-While you can get started with BlockNote in minutes, it's likely that you'll
-want to customize its features and functionality to better suit your app.
-
-## Editor Options
-
-There are a number of options that you can pass to `useCreateBlockNote()`, which you
-can use to customize the editor. You can find the full list of these below:
-
-```typescript
-export type BlockNoteEditorOptions = Partial<{
- initialContent: PartialBlock[];
- domAttributes: Record`, `
`, 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 by the [Image Toolbar](/docs/image-toolbar).
-
-`collaboration`: Options for enabling real-time collaboration. See [Collaboration](/docs/collaboration) for more info.
-
-`blockSpecs` (_advanced_): _advanced_ Specifications for Custom Blocks. See [Block Specs](/docs/block-specs) more info.
-
-`inlineContentSpecs` (_advanced_): Specifications for Custom Inline Content. See [Inline Content Specs](/docs/inline-content-specs) for more info.
-
-`styleSpecs` (_advanced_): Specifications for Custom Styles. See [Style Specs](/docs/style-specs) for more info.
-
-## `useCreateBlockNote`
-
-## `BlockNoteView`
-
-- editable
-- events
-
-### Removing UI Elements
-
-TODO: probably just explain the props of BlockNoteView
-
-In the following example, we remove the Side Menu from the editor. This is done by adding all `Positioner` components as children of `BlockNoteView`, for each UI element except the Side Menu:
-
-
+
+### Block Objects
+
+The `Block` type is used to describe any given block in the editor:
+
+```typescript
+type Block = {
+ id: string;
+ type: string;
+ props: Record;
+ content: InlineContent[] | TableContent | undefined;
+ children: Block[];
+};
+```
+
+`id:` The block's ID. Multiple blocks cannot share a single ID, and a block will keep the same ID from when it's created until it's removed.
+
+`type:` The block's type, such as a paragraph, heading, or list item. For an overview of built-in block types, see [Default Blocks](/docs/editor-basics/default-content-types#default-blocks).
+
+`props:` The block's properties, which is a set of key/value pairs that further specify how the block looks and behaves. Different block types have different props - see [Default Blocks](/docs/editor-basics/default-content-types#default-blocks) for more.
+
+`content:` The block's rich text content, usually represented as an array of `InlineContent` objects. This does not include content from any nested blocks. Read on to [Inline Content](/docs/editor-basics/content-structure#inline-content) for more on this.
+
+`children:` Any blocks nested inside the block. The nested blocks are also represented using `Block` objects.
+
+### Editor Content in JSON
+
+The demo below shows the editor contents (document) in JSON. It's basically an array of `Block` objects that updates as you type in the editor:
+
+;
+ defaultStyles?: boolean;
+ uploadFile?: (file: File) => Promise;
+ collaboration?: CollaborationOptions;
+ schema?: BlockNoteSchema;
+};
+```
+
+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).
+
+`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.
+
+`defaultStyles`: Whether to use the default font and reset the styles of ``, `
`, ``, 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 by the [Image Toolbar](/docs/image-toolbar). TODO
+
+`collaboration`: Options for enabling real-time collaboration. See [Collaboration](/docs/collaboration) for more info.
+
+`schema` (_advanced_): The editor schema if you want to extend your editor with custom blocks, styles, or inline content [Custom Schemas](/docs/custom-schemas).
+
+**deps:** Dependency array that's internally passed to `useMemo`. A new editor will only be created when this array changes.
+
+
+ Manually creating the editor (`BlockNoteEditor.create`)
+
+ The `useCreateBlockNote` hook is actually a simple `useMemo` wrapper around
+ the `BlockNoteEditor.create` method. You can use this method directly if you
+ want to control the editor lifecycle manually. For example, we do this in
+ the [Saving & Loading example](/examples/basic/saving-loading) to delay the
+ editor creation until some content has been fetched from an external data
+ source.
+
+
+
+## Rendering the Editor with ``
+
+Use the `` component to render the `BlockNoteEditor` instance you just created:
+
+```tsx
+const editor = useCreateBlockNote();
+
+return ;
+```
+
+`editor`: The `BlockNoteEditor` instance to render.
+
+`editable`: Whether the editor should be editable.
+
+`onSelectionChange`: Callback for when the editor selection changes.
+
+`onChange`: Callback for when the editor selection or content changes.
+
+`theme`: The editor's theme, see [Themes](/docs/styling-theming/themes) for more about this.
+
+`formattingToolbar`: Whether the [Formatting Toolbar](/docs/ui-components/formatting-toolbar) should be enabled.
+
+`hyperlinkToolbar`: Whether the Hyperlink Toolbar should be enabled.
+
+`sideMenu`: Whether the [Block Side Menu](/docs/ui-components/side-menu) should be enabled.
+
+`slashMenu`: Whether the [Slash Menu](/docs/ui-components/suggestion-menus#slash-menu) should be enabled.
+
+`imageToolbar`: Whether the Image Toolbar should be enabled.
+
+`tableHandles`: Whether the Table Handles should be enabled.
+
+`children`: Pass child elements to the `BlockNoteView` to create or customize toolbars, menus, or other UI components. See [UI Components](/docs/ui-components) for more.
+
+Additional props passed are forwarded to the HTML `div` element BlockNote renders internally.
+
+
+ Uncontrolled component
+
+ Note that the `BlockNoteView` component is an [uncontrolled component](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).
+ This means you don't pass in the editor content directly as a prop. You can use the `initialContent` option in the `useCreateBlockNote` hook to set the initial content of the editor (similar to the `defaultValue` prop in a regular React `
`, `
`, 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 by the [Image Toolbar](/docs/image-toolbar). TODO
+
+`collaboration`: Options for enabling real-time collaboration. See [Collaboration](/docs/collaboration) for more info.
+
+`schema` (_advanced_): The editor schema if you want to extend your editor with custom blocks, styles, or inline content [Custom Schemas](/docs/custom-schemas).
+
+**deps:** Dependency array that's internally passed to `useMemo`. A new editor will only be created when this array changes.
+
+
+ Manually creating the editor (`BlockNoteEditor.create`)
+
+ The `useCreateBlockNote` hook is actually a simple `useMemo` wrapper around
+ the `BlockNoteEditor.create` method. You can use this method directly if you
+ want to control the editor lifecycle manually. For example, we do this in
+ the [Saving & Loading example](/examples/basic/saving-loading) to delay the
+ editor creation until some content has been fetched from an external data
+ source.
+
+
+
+## Rendering the Editor with ``
+
+Use the `` component to render the `BlockNoteEditor` instance you just created:
+
+```tsx
+const editor = useCreateBlockNote();
+
+return ;
+```
+
+`editor`: The `BlockNoteEditor` instance to render.
+
+`editable`: Whether the editor should be editable.
+
+`onSelectionChange`: Callback for when the editor selection changes.
+
+`onChange`: Callback for when the editor selection or content changes.
+
+`theme`: The editor's theme, see [Themes](/docs/styling-theming/themes) for more about this.
+
+`formattingToolbar`: Whether the [Formatting Toolbar](/docs/ui-components/formatting-toolbar) should be enabled.
+
+`hyperlinkToolbar`: Whether the Hyperlink Toolbar should be enabled.
+
+`sideMenu`: Whether the [Block Side Menu](/docs/ui-components/side-menu) should be enabled.
+
+`slashMenu`: Whether the [Slash Menu](/docs/ui-components/suggestion-menus#slash-menu) should be enabled.
+
+`imageToolbar`: Whether the Image Toolbar should be enabled.
+
+`tableHandles`: Whether the Table Handles should be enabled.
+
+`children`: Pass child elements to the `BlockNoteView` to create or customize toolbars, menus, or other UI components. See [UI Components](/docs/ui-components) for more.
+
+Additional props passed are forwarded to the HTML `div` element BlockNote renders internally.
+
+
+ Uncontrolled component
+
+ Note that the `BlockNoteView` component is an [uncontrolled component](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components).
+ This means you don't pass in the editor content directly as a prop. You can use the `initialContent` option in the `useCreateBlockNote` hook to set the initial content of the editor (similar to the `defaultValue` prop in a regular React `
+ The `useCreateBlockNote` hook is actually a simple `useMemo` wrapper around + the `BlockNoteEditor.create` method. You can use this method directly if you + want to control the editor lifecycle manually. For example, we do this in + the [Saving & Loading example](/examples/basic/saving-loading) to delay the + editor creation until some content has been fetched from an external data + source. +
++ Note that the `BlockNoteView` component is an [uncontrolled component](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components). + This means you don't pass in the editor content directly as a prop. You can use the `initialContent` option in the `useCreateBlockNote` hook to set the initial content of the editor (similar to the `defaultValue` prop in a regular React `