Add documentation for useLegacyWrapping option in comments extension (#…

…61)

* added docs for new useLegacyWrapping option for comments extension

* added changesets

* update wording on configuration page

.changeset/stupid-ads-perform.md

@@ -0,0 +1,5 @@
+---
+'tiptap-docs': patch
+---
+
+Added new information about the useLegacyWrapping option for the comments extension.

src/content/comments/core-concepts/configure.mdx

@@ -6,6 +6,8 @@ meta:
   category: Comments
 ---
 
+import { Callout } from '@/components/ui/Callout'
+
 Comments are embedded within documents in the Collaboration Cloud. To enable comments, integrate the TiptapCollabProvider and configure your setup to support comment functionality.
 
 ## provider
@@ -68,3 +70,25 @@ Comments.Configure({
   onClickThread: (id) => console.log('Thread clicked', id),
 })
 ```
+
+## useLegacyWrapping
+
+<Callout title="Warning" variant="warning">
+  The new wrapping mechanism uses a different schema for threads on block nodes, which is not
+  compatible with the previous wrapping behavior. If this is set to `false` without mapping existing
+  thread nodes to the new schema, the threads content will be stripped from the document.
+</Callout>
+
+A boolean option that controls whether to use the legacy wrapping mechanism for multi-line comments. We suggest for new implementations to set this to `false`, and existing integrations can stay on the previous behavior. This is only required for backwards compatibility with existing comments, and it will
+be removed in the future.
+
+The new wrapping mechanism is more flexible, allowing to wrap content more precise and supports mixed wrapping of inline and block nodes.
+
+**Default:** `true`
+
+```js
+Comments.configure({
+  // enable new flexible block wrapping
+  useLegacyWrapping: false,
+})
+```

src/content/comments/getting-started/install.mdx

@@ -50,13 +50,19 @@ const editor = new Editor({
     ...,
     CommentsKit.configure({
       provider: collabProvider,
+      useLegacyWrapping: false, // optional, will be the default in the future
     }),
   ]
 })
 ```
 
 Your editor is now ready to support threads.
 
+<Callout title="Important" variant="warning">
+  The new `useLegacyWrapping` option can be set to false to use a new block wrapping mechanism for
+  multi-line comments. This **will become the default** in the future.
+</Callout>
+
 <hr />
 
 See a full example of how to use the Comments extension in the following example: