Added Invalid Schema Handling

Author: ThisDavidRichard

Diff for: .idea/.name

@@ -61,6 +61,21 @@ Tiptap Guides provide practical advice on configuring your editor, enhancing the
         </Link>
       </CardGrid.Item>
     </FilterGrid.Item>
+    <FilterGrid.Item filter="Editor">
+      <CardGrid.Item asChild>
+        <Link href="/guides/invalid-schema">
+          <CardGrid.Subtitle size="sm">Essential</CardGrid.Subtitle>
+          <div>
+            <CardGrid.ItemTitle>
+                How to handle invalid schemas in Tiptap
+            </CardGrid.ItemTitle>
+          </div>
+          <CardGrid.ItemFooter>
+            <Tag>Editor</Tag>
+          </CardGrid.ItemFooter>
+        </Link>
+      </CardGrid.Item>
+    </FilterGrid.Item>
     <FilterGrid.Item filter="Editor">
       <CardGrid.Item asChild>
         <Link href="/guides/output-json-html">

Diff for: src/content/guides/index.mdx

@@ -0,0 +1,108 @@
+---
+tags:
+  - type: editor
+meta:
+    title: Invalid schema handling | Tiptap Editor Docs
+    description: Adjust and configure how you handle invalid schemas in Tiptap and Tiptap Collaboration. More in the docs!
+    category: editor
+title: Invalid schema handling in Tiptap
+---
+
+Content integrity can be a significant challenge in collaborative editing environments. Think of a scenario where users with different versions of an app are trying to edit the same document. Or a scenario common to single-page applications: some users keep their browser tabs open for long periods of time without refreshing, while others always have the latest editor version after a recent page load.
+
+In both cases, a user with a newer version is creating content with features that are not available to others. When a user with an older version tries to access this document, how do we prevent data loss, maintain document structure, and ensure a smooth user experience?
+
+This is where invalid schema handling becomes important. It allows developers to gracefully manage situations where the content structure doesn't match the editor's expectations, preventing issues like data corruption, unexpected content stripping, or editor crashes.
+
+Whether you're building a note-taking app, a content management system, or any application with rich text editing capabilities, understanding and implementing proper schema handling can significantly improve your application's reliability and user experience.
+
+## Introducing content checking
+
+Tiptap has a option called `enableContentCheck`. When set to `true`, this feature activates a mechanism to validate content against the schema derived from your registered extensions. This is particularly useful for catching and responding to content errors before they cause issues in your application.
+
+### Enable content checking
+
+To enable this feature, simply add the `enableContentCheck` option when initializing your Tiptap editor:
+
+```jsx
+new Editor({
+  enableContentCheck: true,
+  // ... other options
+})
+```
+
+## The contentError event
+
+When content checking is enabled, Tiptap will emit a `contentError` event if the initial content provided during editor setup is incompatible with the schema. This event provides you with valuable information to handle the error appropriately.
+
+### Handle contentError events
+
+You have two options for handling these events:
+
+1. Using the `onContentError` callback:
+
+```jsx
+new Editor({
+  enableContentCheck: true,
+  content: potentiallyInvalidContent,
+  onContentError({ editor, error, disableCollaboration }) {
+    // Your error handling logic here
+  },
+  // ... other options
+})
+
+```
+
+1. Attaching a listener to the `contentError` event:
+
+```jsx
+const editor = new Editor({
+  enableContentCheck: true,
+  content: invalidContent,
+  // ... other options
+})
+
+editor.on('contentError', ({ editor, error, disableCollaboration }) => {
+  // Your error handling logic here
+})
+
+```
+
+## A note on content types
+
+It's important to note that Tiptap's content checking is 100% accurate for JSON content types. However, when working with HTML content, there may be some limitations. While Tiptap does its best to alert on missing nodes, certain mark-related issues might be missed in some situations.
+
+## Recommended error handling strategies
+
+How you handle schema errors will depend on your specific application and requirements. However, here are some general recommendations:
+
+### For non-collaborative editing
+
+If you're not using collaborative editing features, the default behavior of stripping unknown content may be sufficient. This keeps your content in a known valid state for future editing.
+
+### For collaborative editing
+
+When using collaborative features, it's crucial to handle content errors to prevent synchronization issues. Here's an example of how you might handle a content error in a collaborative environment:
+
+```jsx
+onContentError({ editor, error, disableCollaboration }) {
+  // Disable collaboration to prevent syncing invalid content
+  disableCollaboration()
+
+  // Prevent emitting updates
+  const emitUpdate = false
+
+  // Disable further user input
+  editor.setEditable(false, emitUpdate)
+
+  // Notify the user about the issue
+  notifyUser("An error occurred. Please refresh the application.")
+}
+
+```
+
+This approach:
+1. Disables collaboration to prevent syncing invalid content
+2. Prevents updates from being emitted
+3. Disables the editor to prevent further user input
+4. Notifies the user about the issue

Diff for: src/content/guides/invalid-schema.mdx

@@ -29,6 +29,10 @@ export const sidebarConfig: SidebarConfig = {
           href: '/guides/performance',
           title: 'Performance',
         },
+        {
+          href: '/guides/invalid-schema',
+          title: 'Invalid schema handling',
+        },
         {
           href: '/guides/output-json-html',
           title: 'Export JSON or HTML',