feat(core): allow comment & suggestion marks on plain blocks

"plain" blocks (e.g. code blocks) previously disallowed all marks
(`marks: ""`), which also blocked comments and suggestions/diffs. Allow
the non-formatting marks while still excluding formatting.

- Add a shared "annotation" mark group to the comment mark and the
  suggestion marks (insertion/deletion/modification), and reference that
  group from plain blocks' node spec. The always-present suggestion marks
  keep the group non-empty, so the reference resolves even when comments
  aren't configured (the comment mark is conditional).
- Update the stripDisallowedMarks migration to keep these non-formatting
  marks and strip only the disallowed formatting marks, so legacy code
  blocks retain their comments/suggestions.
- Tests: code block allows insertion/deletion/modification (and comment
  when comments are enabled) but not bold; migration keeps comment +
  insertion while stripping bold.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: YousefED

packages/core/src/comments/mark.ts

@@ -1,10 +1,14 @@
 import { Mark, mergeAttributes } from "@tiptap/core";
 
+import { NON_FORMATTING_MARK_GROUP } from "../schema/markGroups.js";
+
 export const CommentMark = Mark.create({
   name: "comment",
   excludes: "",
   inclusive: false,
   keepOnSplit: true,
+  // Allowed on "plain" blocks (e.g. code blocks) via this group.
+  group: NON_FORMATTING_MARK_GROUP,
 
   addAttributes() {
     // Return an object with attribute configuration

packages/core/src/extensions/tiptap-extensions/Suggestions/SuggestionMarks.ts

@@ -1,6 +1,8 @@
 import { Mark } from "@tiptap/core";
 import { MarkSpec } from "prosemirror-model";
 
+import { NON_FORMATTING_MARK_GROUP } from "../../../schema/markGroups.js";
+
 // This copies the marks from @handlewithcare/prosemirror-suggest-changes,
 // but uses the Tiptap Mark API instead so we can use them in BlockNote
 
@@ -10,6 +12,7 @@ export const SuggestionAddMark = Mark.create({
   name: "insertion",
   inclusive: false,
   excludes: "deletion modification insertion",
+  group: NON_FORMATTING_MARK_GROUP,
   addAttributes() {
     return {
       id: { default: null, validate: "number" }, // note: validate is supported in prosemirror but not in tiptap, so this doesn't actually work (considered not critical)
@@ -55,6 +58,7 @@ export const SuggestionDeleteMark = Mark.create({
   name: "deletion",
   inclusive: false,
   excludes: "insertion modification deletion",
+  group: NON_FORMATTING_MARK_GROUP,
   addAttributes() {
     return {
       id: { default: null, validate: "number" }, // note: validate is supported in prosemirror but not in tiptap
@@ -103,6 +107,7 @@ export const SuggestionModificationMark = Mark.create({
   name: "modification",
   inclusive: false,
   excludes: "deletion insertion",
+  group: NON_FORMATTING_MARK_GROUP,
   addAttributes() {
     // note: validate is supported in prosemirror but not in tiptap
     return {

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

@@ -6,6 +6,7 @@ import {
   Extension,
   ExtensionFactoryInstance,
 } from "../../editor/BlockNoteExtension.js";
+import { NON_FORMATTING_MARK_GROUP } from "../markGroups.js";
 import { PropSchema } from "../propTypes.js";
 import {
   getBlockFromPos,
@@ -171,9 +172,13 @@ export function addNodeAndExtensionsToSpec<
         : TContent extends "plain"
           ? "text*"
           : "",
-      // "plain" blocks hold unstyled text only, so disallow marks on them.
-      // TODO: this might need to allow marks for comments and suggestions / diffs
-      marks: blockConfig.content === "plain" ? "" : undefined,
+      // "plain" blocks hold unstyled text, so they disallow formatting marks.
+      // They still allow the non-formatting marks (comments and
+      // suggestions/diffs) — those annotate content without changing it and are
+      // ignored by the block model. The group's always-present suggestion marks
+      // keep this reference valid even when comments aren't configured.
+      marks:
+        blockConfig.content === "plain" ? NON_FORMATTING_MARK_GROUP : undefined,
       group: "blockContent",
       selectable: blockImplementation.meta?.selectable ?? true,
       isolating: blockImplementation.meta?.isolating ?? true,

packages/core/src/schema/markGroups.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vite-plus/test";
+import * as Y from "yjs";
+
+import { CommentsExtension } from "../comments/extension.js";
+import { DefaultThreadStoreAuth } from "../comments/threadstore/DefaultThreadStoreAuth.js";
+import { BlockNoteEditor } from "../editor/BlockNoteEditor.js";
+import { YjsThreadStore } from "../yjs/comments/YjsThreadStore.js";
+
+describe("non-formatting marks on plain blocks", () => {
+  it("allows suggestion marks but not formatting marks on a code block", () => {
+    const editor = BlockNoteEditor.create();
+    const codeBlock = editor.pmSchema.nodes.codeBlock;
+
+    // Suggestion/diff marks (in the "annotation" group) are allowed.
+    expect(codeBlock.allowsMarkType(editor.pmSchema.marks.insertion)).toBe(
+      true,
+    );
+    expect(codeBlock.allowsMarkType(editor.pmSchema.marks.deletion)).toBe(true);
+    expect(codeBlock.allowsMarkType(editor.pmSchema.marks.modification)).toBe(
+      true,
+    );
+
+    // Formatting marks are not.
+    expect(codeBlock.allowsMarkType(editor.pmSchema.marks.bold)).toBe(false);
+  });
+
+  it("allows the comment mark on a code block when comments are enabled", () => {
+    const ydoc = new Y.Doc();
+    const threadStore = new YjsThreadStore(
+      "user-1",
+      ydoc.getMap("threads"),
+      new DefaultThreadStoreAuth("user-1", "editor"),
+    );
+    const editor = BlockNoteEditor.create({
+      extensions: [
+        CommentsExtension({ threadStore, resolveUsers: async () => [] }),
+      ],
+    });
+
+    const commentMark = editor.pmSchema.marks.comment;
+    expect(commentMark).toBeDefined();
+    expect(commentMark.spec.group).toBe("annotation");
+    expect(editor.pmSchema.nodes.codeBlock.allowsMarkType(commentMark)).toBe(
+      true,
+    );
+  });
+});

packages/core/src/schema/markGroups.ts

@@ -0,0 +1,27 @@
+/**
+ * ProseMirror mark group for "non-formatting" marks: comments and
+ * suggestion/diff marks (`insertion`/`deletion`/`modification`). These annotate
+ * content without representing inline formatting and are ignored by BlockNote's
+ * content model (`blocknoteIgnore`).
+ *
+ * They are the only marks allowed on `"plain"` blocks (e.g. code blocks), which
+ * otherwise disallow all marks. A block references this group rather than the
+ * individual marks because the comment mark is only present when comments are
+ * configured — and the always-present suggestion marks keep the group non-empty
+ * so the reference never resolves to an unknown mark/group.
+ */
+export const NON_FORMATTING_MARK_GROUP = "annotation";
+
+/**
+ * The marks that belong to {@link NON_FORMATTING_MARK_GROUP}, by name.
+ *
+ * Yjs schema migrations run before the ProseMirror schema is available, so they
+ * can't read group membership from the schema and use this list instead. Keep
+ * it in sync with the marks that declare `group: NON_FORMATTING_MARK_GROUP`.
+ */
+export const NON_FORMATTING_MARK_NAMES: readonly string[] = [
+  "comment",
+  "insertion",
+  "deletion",
+  "modification",
+];

packages/core/src/yjs/extensions/schemaMigration/migrationRules/stripDisallowedMarks.test.ts

@@ -58,6 +58,45 @@ describe("stripDisallowedMarks rule", () => {
     );
   });
 
+  it("keeps comment and suggestion marks while stripping formatting", () => {
+    const doc = new Y.Doc();
+    const fragment = doc.getXmlFragment("doc");
+    const blockGroup = new Y.XmlElement("blockGroup");
+    const container = new Y.XmlElement("blockContainer");
+    container.setAttribute("id", "code-0");
+    const codeBlock = new Y.XmlElement("codeBlock");
+    codeBlock.setAttribute("language", "javascript");
+    const text = new Y.XmlText();
+    text.insert(0, "const x = 1;");
+    text.format(0, 5, { bold: {} }); // formatting — should be stripped
+    text.format(0, 5, { comment: { threadId: "t1", orphan: false } }); // keep
+    text.format(6, 1, { insertion: { id: 1 } }); // keep
+    codeBlock.insert(0, [text]);
+    container.insert(0, [codeBlock]);
+    blockGroup.insert(0, [container]);
+    fragment.insert(0, [blockGroup]);
+
+    const editor = BlockNoteEditor.create();
+    stripDisallowedMarks(fragment, editor.schema.blockSchema);
+
+    const delta = text.toDelta() as {
+      insert: string;
+      attributes?: Record<string, unknown>;
+    }[];
+    const remaining = new Set<string>();
+    for (const op of delta) {
+      if (op.attributes) {
+        Object.keys(op.attributes).forEach((k) => remaining.add(k));
+      }
+    }
+
+    expect(remaining.has("bold")).toBe(false); // formatting stripped
+    expect(remaining.has("comment")).toBe(true); // comment kept
+    expect(remaining.has("insertion")).toBe(true); // suggestion kept
+    // Text preserved (delta inserts concatenated, ignoring mark tags).
+    expect(delta.map((op) => op.insert).join("")).toBe("const x = 1;");
+  });
+
   it("leaves an already-clean code block untouched", () => {
     const doc = new Y.Doc();
     const fragment = doc.getXmlFragment("doc");

packages/core/src/yjs/extensions/schemaMigration/migrationRules/stripDisallowedMarks.ts

@@ -1,6 +1,7 @@
 import * as Y from "yjs";
 
 import { BlockSchema } from "../../../../schema/index.js";
+import { NON_FORMATTING_MARK_NAMES } from "../../../../schema/markGroups.js";
 import { PreSyncMigrationRule } from "./migrationRule.js";
 
 // Recursively traverses a `Y.XmlElement` and its descendant elements.
@@ -16,8 +17,9 @@ const traverseElement = (
   });
 };
 
-// Removes all formatting (marks) from a `Y.XmlText`. Returns whether anything
-// was removed.
+// Removes formatting marks from a `Y.XmlText`, keeping the non-formatting marks
+// (comments and suggestions/diffs) that a `"plain"` block still allows. Returns
+// whether anything was removed.
 const stripFormatting = (text: Y.XmlText) => {
   const markKeys = new Set<string>();
   for (const op of text.toDelta() as {
@@ -30,31 +32,36 @@ const stripFormatting = (text: Y.XmlText) => {
     }
   }
 
-  if (markKeys.size === 0) {
+  const keysToStrip = [...markKeys].filter(
+    (key) => !NON_FORMATTING_MARK_NAMES.includes(key),
+  );
+
+  if (keysToStrip.length === 0) {
     return false;
   }
 
   // Setting each attribute to `null` removes that mark across the range.
   text.format(
     0,
     text.length,
-    Object.fromEntries([...markKeys].map((key) => [key, null])),
+    Object.fromEntries(keysToStrip.map((key) => [key, null])),
   );
 
   return true;
 };
 
-// Strips marks from the text of `"plain"` content blocks (e.g. code blocks).
+// Strips formatting marks from the text of `"plain"` content blocks (e.g. code
+// blocks).
 //
 // Older documents may contain blocks whose content was previously `"inline"`
-// (and so could hold marks like bold) but is now `"plain"` — whose ProseMirror
-// node disallows marks (`marks: ""`). y-prosemirror does not strip disallowed
-// marks; instead it rejects the whole node (`createChecked` throws) and its
-// error handler DELETES that node from the Yjs document, propagating the
-// deletion to all peers. This rule removes those marks from the fragment so the
-// node stays valid and survives reconstruction (the text itself is preserved;
-// only the formatting — which `"plain"` content cannot represent anyway — is
-// dropped).
+// (and so could hold formatting marks like bold) but is now `"plain"` — whose
+// ProseMirror node only allows the non-formatting marks (comments and
+// suggestions/diffs). y-prosemirror does not strip disallowed marks; instead it
+// rejects the whole node (`createChecked` throws) and its error handler DELETES
+// that node from the Yjs document, propagating the deletion to all peers. This
+// rule removes the disallowed (formatting) marks from the fragment so the node
+// stays valid and survives reconstruction — preserving the text as well as the
+// comment/suggestion marks the block still allows.
 //
 // Unlike the post-sync `MigrationRule`s, this must run BEFORE y-prosemirror
 // reconstructs the document, so it mutates the Yjs fragment directly.