docs: Default block configuration example

docs/content/docs/features/blocks/code-blocks.mdx

@@ -17,38 +17,48 @@ Code blocks by default are a simple way to display code. But, BlockNote also sup
 
 <Callout type="info">
   These features are disabled by default to keep the default code block
-  experience easy to use and reduce bundle size.
+  experience easy to use and reduce bundle size. They can be individually added
+  when [configuring the
+  block](/docs/features/blocks#configuring-default-blocks).
 </Callout>
 
-You can enable more advanced features by extending the editor's default schema with a new `codeBlock`, which you can pass options into when creating. For more on extending the editor schema, see [Custom Schemas](/docs/features/custom-schemas).
+**Configuration Options**
 
 ```ts
-const editor = new BlockNoteEditor({
-  schema: BlockNoteSchema.create().extend({
-    codeBlock: createCodeBlockSpec({
-      indentLineWithTab: true,
-      defaultLanguage: "typescript",
-      supportedLanguages: {
-        typescript: {
-          name: "TypeScript",
-          aliases: ["ts"],
-        },
-      },
-      createHighlighter: () =>
-        createHighlighter({
-          themes: ["light-plus", "dark-plus"],
-          langs: [],
-        }),
-    }),
-  }),
-});
+type CodeBlockOptions = {
+  indentLineWithTab?: boolean;
+  defaultLanguage?: string;
+  supportedLanguages?: Record<
+    string,
+    {
+      name: string;
+      aliases?: string[];
+    }
+  >;
+  createHighlighter?: () => Promise<HighlighterGeneric<any, any>>;
+};
 ```
 
-You can choose to enable only certain features, or none at all. Giving you the flexibility to use code blocks how you need in your app.
+`indentLineWithTab:` Whether the Tab key should indent lines, or not be handled by the code block specially. Defaults to `true`.
+
+`defaultLanguage:` The syntax highlighting default language for code blocks which are created/inserted without a set language, which is `text` by default (no syntax highlighting).
+
+`supportedLanguages:` The syntax highlighting languages supported by the code block, which is an empty array by default.
 
-## Block Shape
+`createHighlighter:` The [Shiki highliter](https://shiki.style/guide/load-theme) to use for syntax highlighting.
 
-This describes the shape of a code block in BlockNote.
+BlockNote also provides a generic set of options for syntax highlighting in the `@blocknote/code-block` package, which support a wide range of languages:
+
+```ts
+import { createCodeBlockSpec } from "@blocknote/core";
+import { codeBlockOptions } from "@blocknote/code-block";
+
+const codeBlock = createCodeBlockSpec(codeBlockOptions);
+```
+
+See [this example](/examples/theming/code-block) to see it in action.
+
+**Type & Props**
 
 ```ts
 type CodeBlock = {
@@ -62,45 +72,13 @@ type CodeBlock = {
 };
 ```
 
-## Options
-
-### Basic Setup
-
-To enable code block syntax highlighting, you can extend the editor's default schema with a new `codeBlock`.
-
-First, install the package:
-
-```sh
-npm install @blocknote/code-block
-```
-
-Then use it like this:
-
-```tsx
-import { codeBlockOptions } from "@blocknote/code-block";
-
-export default function App() {
-  const editor = useCreateBlockNote({
-    schema: BlockNoteSchema.create().extend({
-      codeBlock: createCodeBlockSpec(codeBlockOptions),
-    }),
-  });
-
-  return <BlockNoteView editor={editor} />;
-}
-```
-
-This will extend the default schema with a custom `codeBlock` that includes options from `@blocknote/code-block`, enabling syntax highlighting.
-
-### Custom Themes & Languages
-
-To configure a code block highlighting theme and language, you can again extend the editor's default schema with a new `codeBlock`.
+`language:` The syntax highlighting language to use. Defaults to `text`, which has no highlighting.
 
-This allows you to configure a [shiki](https://shiki.style) highlighter for the code blocks of your editor, allowing you to tailor the themes and languages you would like to use.
+## Custom Syntax Highlighting
 
-To create a syntax highlighter, you can use the [shiki-codegen](https://shiki.style/packages/codegen) CLI for generating the code to create a syntax highlighter for your languages and themes.
+To create your own syntax highlighter, you can use the [shiki-codegen](https://shiki.style/packages/codegen) CLI for generating the code to create one for your chosen languages and themes.
 
-For example to create a syntax highlighter using the optimized javascript engine, javascript, typescript, vue, with light and dark themes, you can run the following command:
+For example, to create a syntax highlighter using the optimized javascript engine, javascript, typescript, vue, with light and dark themes, you can run the following command:
 
 ```bash
 npx shiki-codegen --langs javascript,typescript,vue --themes light,dark --engine javascript --precompiled ./shiki.bundle.ts

docs/content/docs/features/blocks/embeds.mdx

@@ -10,8 +10,6 @@ Embeds are a way to display content from external sources in your documents. Blo
 
 ## File
 
-A file block is a block that displays a file.
-
 **Type & Props**
 
 ```ts
@@ -36,7 +34,15 @@ type FileBlock = {
 
 ## Image
 
-An image block is a block that displays an image.
+**Configuration Options**
+
+```ts
+type ImageBlockOptions = {
+  icon?: string;
+};
+```
+
+`icon:` The HTML string for an icon SVG. If no URL is given, the image block displays a button to add one using a link or file, and the provided SVG replaces the generic file icon in that button.
 
 **Type & Props**
 
@@ -64,7 +70,15 @@ type ImageBlock = {
 
 ## Video
 
-A video block is a block that displays a video.
+**Configuration Options**
+
+```ts
+type VideoBlockOptions = {
+  icon?: string;
+};
+```
+
+`icon:` The HTML string for an icon SVG. If no URL is given, the video block displays a button to add one using a link or file, and the provided SVG replaces the generic file icon in that button.
 
 **Type & Props**
 
@@ -96,7 +110,15 @@ type VideoBlock = {
 
 ## Audio
 
-An audio block is a block that displays an audio file.
+**Configuration Options**
+
+```ts
+type AudioBlockOptions = {
+  icon?: string;
+};
+```
+
+`icon:` The HTML string for an icon SVG. If no URL is given, the audio block displays a button to add one using a link or file, and the provided SVG replaces the generic file icon in that button.
 
 **Type & Props**
 

docs/content/docs/features/blocks/index.mdx

@@ -12,7 +12,7 @@ The demo below showcases each of BlockNote's built-in block and inline content t
 
 <Example name="basic/default-blocks" />
 
-### Default Block Properties
+## Default Block Properties
 
 There are some default block props that BlockNote uses for the built-in blocks:
 
@@ -36,6 +36,38 @@ type DefaultProps = {
 };
 ```
 
+## Configuring Default Blocks
+
+Some default blocks can be configured with options. For example, headings can be configured to have different available levels:
+
+```ts
+// Creates a new instance of the default heading block.
+const heading = createHeadingBlockSpec({
+  // Sets the block to support only heading levels 1-3.
+  levels: [1, 2, 3],
+});
+```
+
+Each default block type can be instantiated using their respective `create...BlockSpec` function. If the block can be configured, i.e. if it has options, you can pass them in an object to the function. To see which options each block type supports, read on to the next pages.
+
+To add your configured block to the editor, you must pass in a [custom schema](/docs/features/custom-schemas) with it. The simplest way to do this is by [extending the default schema](/docs/features/custom-schemas#extending-an-existing-schema):
+
+```ts
+const editor = useCreateBlockNote({
+  // Creates a default schema and extends it with the configured heading block.
+  schema: BlockNoteSchema.create().extend({
+    blockSpecs: {
+      heading: createHeadingBlockSpec({
+        // Sets the allowed heading levels.
+        levels: [1, 2, 3],
+      }),
+    },
+  }),
+});
+```
+
+You can see this in action in a working demo [here](/examples/custom-schema/configuring-blocks).
+
 ## Explore
 
 <CardTable path="features/blocks" />

docs/content/docs/features/blocks/typography.mdx

@@ -24,6 +24,22 @@ type ParagraphBlock = {
 
 ## Heading
 
+**Configuration Options**
+
+```typescript
+type HeadingBlockOptions = Partial<{
+  defaultLevel?: number;
+  levels?: number[];
+  allowToggleHeadings?: boolean;
+}>;
+```
+
+`defaultLevel:` The default level for headings which are created/inserted without a set level, which is `1` by default.
+
+`levels:` The heading levels that the block supports, or '1'-'6' by default.
+
+`allowToggleHeadings:` Whether toggle headings should be supported, `true` by default. Toggle headings have a button which toggles between hiding and showing the block's children.
+
 **Type & Props**
 
 ```typescript

docs/package.json

@@ -55,7 +55,7 @@
     "@shikijs/engine-javascript": "^3.2.1",
     "@shikijs/langs-precompiled": "^3.2.1",
     "@shikijs/themes": "^3.2.1",
-    "@shikijs/types": "^3.13.0",
+    "@shikijs/types": "^3.2.1",
     "@tiptap/core": "^3.4.3",
     "@uppy/core": "^3.13.1",
     "@uppy/dashboard": "^3.9.1",
@@ -142,4 +142,4 @@
     "y-partykit": "^0.0.33",
     "yjs": "^13.6.27"
   }
-}
+}

examples/01-basic/01-minimal/package.json

@@ -28,4 +28,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/01-basic/02-block-objects/package.json

@@ -28,4 +28,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/01-basic/03-multi-column/package.json

@@ -29,4 +29,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/01-basic/04-default-blocks/package.json

@@ -28,4 +28,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/01-basic/05-removing-default-blocks/package.json

@@ -28,4 +28,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/01-basic/06-block-manipulation/package.json

@@ -28,4 +28,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/01-basic/07-selection-blocks/package.json

@@ -28,4 +28,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/01-basic/08-ariakit/package.json

@@ -28,4 +28,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/01-basic/09-shadcn/package.json

@@ -31,4 +31,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/01-basic/10-localization/package.json

@@ -28,4 +28,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/01-basic/11-custom-placeholder/package.json

@@ -28,4 +28,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/01-basic/12-multi-editor/package.json

@@ -28,4 +28,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/01-basic/13-custom-paste-handler/package.json

@@ -28,4 +28,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/01-basic/testing/package.json

@@ -28,4 +28,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/02-backend/01-file-uploading/package.json

@@ -28,4 +28,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/02-backend/02-saving-loading/package.json

@@ -28,4 +28,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/02-backend/03-s3/package.json

@@ -30,4 +30,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}

examples/02-backend/04-rendering-static-documents/package.json

@@ -29,4 +29,4 @@
     "@vitejs/plugin-react": "^4.3.1",
     "vite": "^5.3.4"
   }
-}
+}