refactor: move all blocks to use the custom blocks API #1904

nperez0111 · 2025-08-01T08:11:05Z

TODO:

Move the main BlockNoteSchema to use these new blocks (using a base schema which does not include the default blocks so that tree-shaking can drop the blocks if needed)
- sub package?
Merge BlockConfig, BlockImplementation into actual schema
Figure out what to do with blocks that cannot be migrated over (table blocks only?)
Check compatibility with: html/markdown, multi-column
File blocks, why are they special? Try to streamline them into "just" a custom block. Remove type guards for them, and try to replace them with something more generic or whatever they actually need.

vercel · 2025-08-01T08:11:10Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
blocknote	❌ Failed (Inspect)		Aug 4, 2025 4:13pm
blocknote-website	❌ Failed (Inspect)		Aug 4, 2025 4:13pm

matthewlipski

Looks good! Just kind of glanced over everything for now with mostly questions

matthewlipski · 2025-08-01T14:53:22Z

packages/core/src/schema/blocks/createSpec.ts

@@ -111,6 +117,37 @@ export function getParseRules(

        return props;
      },
+      getContent:


Do you think it would be possible to return the content element in the parse function, instead of having a separate parseContent? Because I know they're split in the PM API, but I think it would be more intuitive to merge them into 1 function for the custom block API.

Yea, I thought about this too. Right now, it is pretty easy to do a mapping of HTML -> BlockNote node. But what isn't clear is how to do that mapping for parsing of inner content. We've been going through Prosemirror DOMParser & doing this low-level. I tried a couple of different approaches to do it more high-level & couldn't figure out anything satisfactory.

So, I went with the approach of a "good default", (merge paragraphs to preserve content within the parsed element), and left the rest as an exercise for later. I think what will be useful in this is when we separate out the HTML parsing & exporting from the editor instance, then maybe it will be easier for consumers to parse HTML into the shape that they need 🤷. I marked it as an "advanced" API so that it is clear we are not happy with it. Right now the only time that any of the default blocks need to use parseContent is the list item types, because we added better handling of HTML -> list items.

matthewlipski · 2025-08-01T14:55:29Z

packages/core/src/blks/NumberedListItem/IndexingPlugin.ts

+      );
+
+      if (existingDecorations.length === 0) {
+        // Create a widget decoration to display the index


Comment needs updating

matthewlipski · 2025-08-01T14:59:40Z

packages/core/src/blocks/defaultBlockTypeGuards.ts

@@ -32,8 +32,8 @@ export function checkDefaultBlockTypeInSchema<
  S
 > {
  return (
-    blockType in editor.schema.blockSchema &&
-    editor.schema.blockSchema[blockType] === defaultBlockSchema[blockType]
+    blockType in editor.schema.blockSchema //&&


This is just a temp change while the updated blocks are not yet in the default schema right?

matthewlipski · 2025-08-01T15:03:14Z

packages/core/src/editor/BlockNoteEditor.ts

+              name: key,
+              priority: ext.priority,
+              addProseMirrorPlugins: () => ext.plugins,
+              // TODO maybe collect all input rules from all extensions into one plugin


I think it's more intuitive to keep logic for a block/extension within the same extension

matthewlipski · 2025-08-01T15:03:49Z

packages/core/src/editor/BlockNoteSchema.ts

@@ -105,3 +105,6 @@ export class BlockNoteSchema<
    this.styleSchema = getStyleSchemaFromSpecs(this.styleSpecs) as any;
  }
 }
+


TODO: Remove?

matthewlipski · 2025-08-01T15:08:01Z

packages/core/src/schema/blocks/types.ts

@@ -21,6 +21,8 @@ export type BlockNoteDOMAttributes = Partial<{
  [DOMElement in BlockNoteDOMElement]: Record<string, string>;
 }>;

+// TODO we should remove FileBlockConfig, and only use BlockConfig
+// Ideally something like this would be represented via `groups: ["file"]` or similar


Could we add a file field to the new meta property in the config?

I'm not sure on this. It feels wrong to me that files are somehow different. Like why is there a file field & not a listItem field? I am not in favor of adding more properties than needed, since it adds complexity to each custom block that people can add.

I don't fully understand why this is even required at this point

matthewlipski · 2025-08-01T15:09:38Z

packages/core/src/util/topo-sort.ts

@@ -0,0 +1,154 @@
+// Based on https://github.com/n1ru4l/toposort/blob/main/src/toposort.ts (MIT)


Could you add a comment for why this file was added?

YousefED

nice. posted some first thoughts / questions!

YousefED · 2025-08-04T06:23:18Z

packages/core/src/blks/BulletListItem/definition.ts

+            return true;
+          }),
+      },
+      inputRules: [


cool that there's a BN-style API for this. Can we do the same for keyboardshortcuts you think?

I thought about what that would look like for keyboard shortcuts, but the problem is that keyboard shortcuts can sort of just do anything. Some usecases I thought of were:

bringing up some menu items

triggering some action (e.g. stop AI generation)

inserting a new element

modifying an existing block

These sorts of cases are too disparate to really "unify" into a sensible API. Fundamental tension between composability & centralization.

YousefED · 2025-08-04T06:27:55Z

packages/core/src/schema/blocks/playground.ts

+   * Advanced parsing function that controls how content within the block is parsed.
+   * This is not recommended to use, and is only useful for advanced use cases.
+   */
+  parseContent?: (options: { el: HTMLElement; schema: Schema }) => Fragment;


would be nice to do this in a way that we don't expose Prosemirror APIs (i.e.: not expose Fragment) - not sure this is possible

#1904 (comment)

Yea I couldn't find a great way to do this. Especially given that the only case that really needs this are list items

YousefED · 2025-08-04T06:29:18Z

packages/core/src/schema/blocks/playground.ts

+     * The BlockNote editor instance
+     */
+    editor: BlockNoteEditor<Record<TName, BlockConfig<TName, TProps>>>,
+  ) => {


These functions (dom / contentDOM / ignoreMutation) are very prosemirror specific. For now out of scope (as they're also in the existing API and this PR is about moving blocks over), but don't think this is ideal

Yep, agreed, but not looking to rock that boat right now

YousefED · 2025-08-04T06:40:11Z

packages/core/src/blks/BulletListItem/definition.ts

+    },
+  }),
+  () => [
+    createBlockNoteExtension({


What was the reasoning again to define keyboardshortcuts / inputrules in a separate argument + createBlockNoteExtension?

This introduces keyboard shortcuts & inputrules to the extension API because we didn't have a way of doing them before.

I considered exposing them to both APIs (e.g. a custom block has an input rule API & so does the extension API), but that only added complexity.

Allowing extensions to be included to the block API is useful in that some things may require an extension to function (e.g. code block syntax highlighting, numbered list decorations).

nperez0111 added 3 commits July 28, 2025 12:59

feat: wip

fcdbf18

feat: topological sorting, input rules and keyboard shortcuts

e1bb45e

feat: move code block over too

6b10846

feat: getContent parsing for custom blocks

92952e7

vercel bot had a problem deploying to Preview – blocknote August 1, 2025 10:22 Failure

vercel bot had a problem deploying to Preview – blocknote-website August 1, 2025 10:23 Failure

nperez0111 added 3 commits August 1, 2025 15:28

fix: render toggle lists

6d85ef5

fix: toggle headings

ec77940

refactor: custom schema, which depends on no blocks

809ea0a

vercel bot had a problem deploying to Preview – blocknote August 1, 2025 13:39 Failure

vercel bot had a problem deploying to Preview – blocknote-website August 1, 2025 13:40 Failure

matthewlipski reviewed Aug 1, 2025

View reviewed changes

YousefED reviewed Aug 4, 2025

View reviewed changes

nperez0111 added 2 commits August 4, 2025 17:59

refactor: trying to fit it in

b46fcc6

fix: get tables working

5751974

vercel bot had a problem deploying to Preview – blocknote August 4, 2025 16:12 Failure

vercel bot had a problem deploying to Preview – blocknote-website August 4, 2025 16:13 Failure

		@@ -0,0 +1,154 @@
		// Based on https://github.com/n1ru4l/toposort/blob/main/src/toposort.ts (MIT)

Uh oh!

refactor: move all blocks to use the custom blocks API #1904

Are you sure you want to change the base?

refactor: move all blocks to use the custom blocks API #1904

Uh oh!

Conversation

nperez0111 commented Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

matthewlipski left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

YousefED left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nperez0111 commented Aug 1, 2025 •

edited

Loading

vercel bot commented Aug 1, 2025 •

edited

Loading