Skip to content

fix: add context,nestingLevel to toExternalHTML #2373

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
matthewlipski merged 3 commits into from
Jan 27, 2026
+30 −6
Merged

fix: add context,nestingLevel to toExternalHTML #2373

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
71cdb89
fix: add contaxt,nestingLevel to toExternalHTML
YousefED Jan 21, 2026
0df0943
Added docs
matthewlipski Jan 27, 2026
1d8d697
Merge branch 'main' into fix/nesting-level-external
matthewlipski Jan 27, 2026
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
5 changes: 4 additions & 1 deletion docs/content/docs/features/custom-schemas/custom-blocks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,7 @@ type ReactCustomBlockImplementation = {
block: Block;
editor: BlockNoteEditor;
contentRef?: (node: HTMLElement | null) => void;
contest: { nestingLevel: number };
}>;
parse?: (element: HTMLElement) => PartialBlock["props"] | undefined;
runsBefore?: string[];
Expand All @@ -143,7 +144,9 @@ type ReactCustomBlockImplementation = {

- `contentRef:` A React `ref` you can use to mark which element in your block is editable, this is only available if your block config contains `content: "inline"`.

`toExternalHTML?:` This component is used whenever the block is being exported to HTML for use outside BlockNote, for example when copying it to the clipboard. If it's not defined, BlockNote will just use `render` for the HTML conversion. Takes the same props as `render`.
`toExternalHTML?:` This component is used whenever the block is being exported to HTML for use outside BlockNote, for example when copying it to the clipboard. If it's not defined, BlockNote will just use `render` for the HTML conversion. Takes the same props as `render` and an additional `context` prop, which is. an object with the following attributes:

- `nestingLevel`: How deep the block being exported in nested inside other blocks. 0 means it's at the top level of the document.

<Callout type="info">
_Note that your component passed to `toExternalHTML` is rendered and
Expand Down
3 changes: 3 additions & 0 deletions packages/core/src/api/exporters/html/util/serializeBlocksExternalHTML.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,9 @@ function serializeBlock<
{},
{ ...block, props } as any,
editor as any,
{
nestingLevel,
},
) ||
blockImplementation.render.call(
{},
Expand Down
6 changes: 4 additions & 2 deletions packages/core/src/schema/blocks/createSpec.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,7 +242,7 @@ export function addNodeAndExtensionsToSpec<
},
// TODO: this should not have wrapInBlockStructure and generally be a lot simpler
// post-processing in externalHTMLExporter should not be necessary
toExternalHTML: (block, editor) => {
toExternalHTML: (block, editor, context) => {
const blockContentDOMAttributes =
node.options.domAttributes?.blockContent || {};

Expand All @@ -251,6 +251,7 @@ export function addNodeAndExtensionsToSpec<
{ blockContentDOMAttributes },
block as any,
editor as any,
context,
) ??
blockImplementation.render.call(
{ blockContentDOMAttributes, renderType: "dom", props: undefined },
Expand Down Expand Up @@ -393,11 +394,12 @@ export function createBlockSpec<
...blockImplementation,
// TODO: this should not have wrapInBlockStructure and generally be a lot simpler
// post-processing in externalHTMLExporter should not be necessary
toExternalHTML(block, editor) {
toExternalHTML(block, editor, context) {
const output = blockImplementation.toExternalHTML?.call(
{ blockContentDOMAttributes: this.blockContentDOMAttributes },
block as any,
editor as any,
context,
);

if (output === undefined) {
Expand Down
9 changes: 9 additions & 0 deletions packages/core/src/schema/blocks/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,9 @@ export type LooseBlockSpec<
toExternalHTML?: (
block: any,
editor: BlockNoteEditor<any>,
context: {
nestingLevel: number;
},
) =>
| {
dom: HTMLElement | DocumentFragment;
Expand Down Expand Up @@ -193,6 +196,9 @@ export type BlockSpecs = {
toExternalHTML?: (
block: any,
editor: BlockNoteEditor<any>,
context: {
nestingLevel: number;
},
) =>
| {
dom: HTMLElement | DocumentFragment;
Expand Down Expand Up @@ -463,6 +469,9 @@ export type BlockImplementation<
editor: BlockNoteEditor<
Record<TName, BlockConfig<TName, TProps, TContent>>
>,
context: {
nestingLevel: number;
},
) =>
| {
dom: HTMLElement | DocumentFragment;
Expand Down
13 changes: 10 additions & 3 deletions packages/react/src/schema/ReactBlockSpec.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@ import {
BlockImplementation,
BlockNoDefaults,
BlockNoteEditor,
Extension,
BlockSpec,
camelToDataKebab,
CustomBlockImplementation,
Extension,
getBlockFromPos,
mergeCSSClasses,
Props,
Expand Down Expand Up @@ -51,7 +51,13 @@ export type ReactCustomBlockImplementation<
"render" | "toExternalHTML"
> & {
render: FC<ReactCustomBlockRenderProps<TName, TProps, TContent>>;
toExternalHTML?: FC<ReactCustomBlockRenderProps<TName, TProps, TContent>>;
toExternalHTML?: FC<
ReactCustomBlockRenderProps<TName, TProps, TContent> & {
context: {
nestingLevel: number;
};
}
>;
};

export type ReactCustomBlockSpec<
Expand Down Expand Up @@ -224,7 +230,7 @@ export function createReactBlockSpec<
config: blockConfig,
implementation: {
...blockImplementation,
toExternalHTML(block, editor) {
toExternalHTML(block, editor, context) {
const BlockContent =
blockImplementation.toExternalHTML || blockImplementation.render;
const output = renderToDOMSpec((refCB) => {
Expand All @@ -247,6 +253,7 @@ export function createReactBlockSpec<
);
}
}}
context={context}
/>
</BlockContentWrapper>
);
Expand Down
Loading