fix: External HTML parse/export cases

[matthewlipski]

Implemented Changes

This PR adds the non-breaking changes from #1605, updating them to work with the default blocks refactor. These are:

Styles:

• Adding text/background color style parsing from inline styles.

Props:

• Adding text/background color prop exporting to inline styles.
• Adding text alignment prop parsing from inline styles.
• Adding text alignment prop exporting to inline styles.
• Fixing start prop parsing for ordered list items.
• Moving responsibility of parsing text alignment from proprietary TipTap extension to custom blocks API. This is done so that it behaves like other props, as it's currently inconsistent.

Tests:

• Added unit tests for new text/background parsing logic.
• Updated snapshots for HTML export tests.

Missing Changes

There are still changes that are relevant for this PR that are either breaking or cannot be implemented atm:

• Text/background color styles cannot currently be exported to inline styles. This is because we create TipTap marks for these, and create BlockNote styles from those marks. When we did smth similar creating default blocks from TipTap nodes, this was fine as we could separate the "internal" and "external" HTML using addNodeView and render. But we can't do this for styles as addMarkView is not supported in TipTap v2, so we'd need to upgrade to v3. Also, if we wanted to use the custom style API instead to create the text & background color styles, this is also a problem as toExternalHTML is not in the API. Adding this would also require addMarkView. There is a hack in the React package that we use to add a mark view, but this seems to have its own issues (see Text disapears when composing #1849).
• Text/background color props cannot currently be parsed from inline styles. This is because the TipTap attributes for these props are set on the blockContainer node, meaning it's responsible for parsing the attributes from HTML. However, when parsing external HTML, we never actually parse anything as a blockContainer, so the text/background color attributes can never be parsed either. To fix this, we'd need to move the attributes to be on content nodes (paragraph, heading, etc) like text alignment currently is. The issue with this is that it changes the underlying BlockNote schema, making this a breaking change for any apps that store the TipTap/PM state underlying BlockNote (notably YDocs for collaboration).

Next steps

• Update TipTap to v3 for mark view support, so that the text/background color styles can be exported to inline styles in "external" HTML. Ideally, we would use this to add toExternalHTML to the custom styles API, and redefine text/background color using the custom styles API directly rather than porting TipTap marks.
• Figure out how to handle migrating collaborative docs to a new underlying TipTap/PM schema. This way, we can move the text/background color attributes out of blockContainer nodes and fix parsing them from inline styles in external HTML, without it being a breaking change.
• Advanced table cells can also have text/background colors. Since tables are still created using createBlockSpecFromTiptapNode, handling exporting/parsing to/from inline styles must be done differently to the other default blocks. I think this is doable, but haven't looked super far into this yet.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
blocknote	Error		Sep 12, 2025 3:58pm
blocknote-website	Ready	Preview	Sep 12, 2025 3:58pm

[nperez0111]

Why use a CSS variable? Can't BlockNote use the data-text-color attribute, and everything else can just get the raw color that is set?

[matthewlipski]

Fixed this in #1998

[pkg-pr-new]

Open in StackBlitz

@blocknote/ariakit

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/ariakit@1991

@blocknote/code-block

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/code-block@1991

@blocknote/core

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/core@1991

@blocknote/mantine

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/mantine@1991

@blocknote/react

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/react@1991

@blocknote/server-util

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/server-util@1991

@blocknote/shadcn

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/shadcn@1991

@blocknote/xl-ai

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-ai@1991

@blocknote/xl-docx-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-docx-exporter@1991

@blocknote/xl-email-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-email-exporter@1991

@blocknote/xl-multi-column

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-multi-column@1991

@blocknote/xl-odt-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-odt-exporter@1991

@blocknote/xl-pdf-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-pdf-exporter@1991

commit: f629634

[nperez0111]

Good add.

[nperez0111]

Intentionally not an exact type?

[matthewlipski]

Yep correct I was running into an issue with that somewhere, IIRC it was parsed color strings from HTML were just regular strings and the default colors keys were a union of string literals, so there was a mismatch.