Merge branch 'main' of github.com:ueberdosis/tiptap-docs into develop…

…ment

src/content/collaboration/documents/convert-api.mdx → src/content/collaboration/documents/conversion.mdx

@@ -1,24 +1,30 @@
 ---
-title: Convert API Reference
+title: Document conversion API
 meta:
-  title: Convert API Reference | Tiptap Collaboration
+  title: Document conversion API | Tiptap Collaboration
   description: Use Tiptap to convert documents from docx, odt or markdown to Tiptap
   category: Collaboration
 ---
+import { Callout } from '@/components/ui/Callout'
 
-## Tiptap Editor extensions
+The document conversion API is capable of DOCX, ODT and Markdown conversion from and to Tiptap’s JSON format.
 
-Instead of using the Convert API directly, you can use the Tiptap Editor extensions to import and export documents.
+<Callout title="Review the postman collection" variant="hint">
+    You can also experiment with the Document Conversion API by heading over to our [Postman
+    Collection](https://www.postman.com/docking-module-explorer-14290287/workspace/tiptap-collaboration-public/collection/33042171-cc186a66-df41-4df8-9c6e-e91b20deffe5?action=share&creator=32651125).
+</Callout>
 
-- [Import Extension](/editor/extensions/functionality/import)
-- [Export Extension](/editor/extensions/functionality/export)
+## Integrate into the editor
+Tiptap offers editor extensions for importing and exporting documents. These extensions integrate the document conversion api.
+So, instead of using the Document Conversion API directly, you can use the import and export Tiptap Editor extensions:
+- [Editor Import Extension](/editor/extensions/functionality/import)
+- [Editor Export Extension](/editor/extensions/functionality/export)
 
-## /import
+## /import endpoint
+The /import endpoint enables the conversion of `docx`, `odt`, or `markdown` files into Tiptap’s JSON format. Users can POST documents to this endpoint and use various parameters to customize how different document elements are handled during the conversion process.
 
 - **Method**: `POST`
 
-Convert a document to a Tiptap document.
-
 ### Required headers
 
 | Name            | Description                                                                                                                                     |
@@ -33,6 +39,7 @@ Convert a document to a Tiptap document.
 | `file` | `File` | The file to convert |
 
 ### Query parameters
+Specify how source document elements should be mapped to ProseMirror nodes or marks and adjust the conversion to meet your specific styling and structural preferences.
 
 | Name             | Default          | Description                                                          |
 | ---------------- | ---------------- | -------------------------------------------------------------------- |
@@ -56,7 +63,9 @@ Convert a document to a Tiptap document.
 | `link`           | `link`           | Defines which prosemirror mark is used for link conversion           |
 | `code`           | `code`           | Defines which prosemirror mark is used for code conversion           |
 
-## /export
+## /export endpoint
+The /export endpoint converts Tiptap documents back into formats like `docx`, `odt`, or `markdown`.
+
 
 - **Method**: `POST`
 

src/content/collaboration/sidebar.ts

@@ -76,8 +76,8 @@ export const sidebarConfig: SidebarConfig = {
           href: '/collaboration/documents/content-injection',
         },
         {
-          title: 'Convert API',
-          href: '/collaboration/documents/convert-api',
+          title: 'Conversion',
+          href: '/collaboration/documents/conversion',
           tags: ['Beta'],
         },
       ],

src/content/editor/extensions/functionality/export.mdx

@@ -19,7 +19,7 @@ extension:
 import { Callout } from '@/components/ui/Callout'
 import { CodeDemo } from '@/components/CodeDemo'
 
-Export documents from various formats like docx, odt, and markdown and convert them from Tiptap's JSON format.
+Export Tiptap's editor content to various formats like docx, odt, and markdown.
 
 <Callout title="Beta release" variant="hint">
   This extension is accessible to anyone with a Tiptap account. To install the extension you need
@@ -110,7 +110,7 @@ const editor = new Editor({
 ```js
 // Do a simple export to docx
 // Supported formats: docx, odt, md and gfm
-editor.chain().export({ format: 'docx' }).focus().run()
+editor.chain().focus().export({ format: 'docx' }).run()
 ```
 
 ### Customize the export behavior
@@ -182,4 +182,4 @@ We're continuously working on improving the import & export extension, so if you
 
 ## More information
 
-- [Convert API Reference](/collaboration/documents/convert-api)
+- [Conversion API Reference](/collaboration/documents/conversion)

src/content/editor/extensions/functionality/import.mdx

@@ -120,7 +120,7 @@ const editor = new Editor({
 // The most simple way to import a file
 // This will import the uploaded file, replace the editor content
 // and focus the editor
-editor.chain().import({ file }).focus().run()
+editor.chain().focus().import({ file }).run()
 ```
 
 ### Customize the import behavior
@@ -197,4 +197,4 @@ We're continuously working on improving the import & export extension, so if you
 
 ## More information
 
-- [Convert API Reference](/collaboration/documents/convert-api)
+- [Conversion API Reference](/collaboration/documents/conversion)

src/content/editor/getting-started/install/react.mdx

@@ -144,3 +144,6 @@ Since the EditorContent component is rendered by the `EditorProvider` component,
   slotAfter={<MyEditorFooter />}
 />
 ```
+
+## Optimize your performance
+We strongly recommend visiting the [React Performance Guide](/guides/performance) to integrate the Tiptap Editor efficiently. This will help you avoid potential issues as your app scales.

src/content/examples/advanced/react-performance.mdx

@@ -0,0 +1,15 @@
+---
+title: React rendering performance
+meta:
+  title: React rendering performance demo | Tiptap Editor Docs
+  description: Learn how to integrate Tiptap with React and improve the rendering performance of your editor. More in the docs!
+  category: Examples
+---
+
+import { CodeDemo } from '@/components/CodeDemo'
+
+## React Tiptap Editor Integration
+
+When using Tiptap with React, the most common performance issue is that the editor is re-rendered too often. This demo shows the difference between the default editor and the optimized rendering with `shouldRerenderOnTransaction`.
+
+<CodeDemo path="/Examples/Performance" />

src/content/examples/sidebar.ts

@@ -80,6 +80,10 @@ export const sidebarConfig: SidebarConfig = {
           title: 'Interactive React & Vue views',
           href: '/examples/advanced/interactive-react-and-vue-views',
         },
+        {
+          title: 'React performance',
+          href: '/examples/advanced/react-performance',
+        },
         {
           title: 'Menus',
           href: '/examples/advanced/menus',

src/content/guides/index.mdx

@@ -46,6 +46,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/performance">
+          <CardGrid.Subtitle size="sm">Essential</CardGrid.Subtitle>
+          <div>
+            <CardGrid.ItemTitle>
+              How to make sure your editor is integrated performantly?
+            </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">

src/content/guides/performance.mdx

@@ -16,12 +16,14 @@ Tiptap is a very performant editor (even able to edit an entire book!), often wh
 
 ## React Tiptap Editor Integration
 
+<CodeDemo path="/Examples/Performance?hideSource=true" />
+
 When using Tiptap with React, the most common performance issue is that the editor is re-rendered too often. This can happen for several reasons:
 
 - When using the `useEditor` hook, it by default will re-render the editor on every change. So, you should isolate the editor (and things that depend on it) in a separate component to prevent unnecessary re-renders.
 - The editor should be isolated from renders that don't affect it. For example, if you have a sidebar that doesn't interact with the editor, it should be in a separate component.
 
-Luckily the solution for most of these issues is the same: isolate the editor in a separate component. Here is an example of how you can do this:
+Luckily, the solution for most of these issues is the same: isolate the editor in a separate component. Here is an example of how you can do this:
 
 DO: isolate the editor in a separate component
 
@@ -75,10 +77,62 @@ export default App
 
 These unrelated components will cause the editor to re-render more often than necessary, and make each render more expensive.
 
-We are working on a more advanced solution to this problem, but for now, this is the best way to ensure your editor runs smoothly.
+### Gain more control over rendering
+
+As of Tiptap v2.5.0, you can gain more control over rendering by using the `immediatelyRender` and `shouldRerenderOnTransaction` options. This can be useful if you want to prevent the editor from rendering immediately or on every transaction.
+
+```tsx
+import { useEditor } from '@tiptap/react'
+import deepEqual from 'deep-equal'
+
+function Component() {
+  const editor = useEditor({
+    extensions,
+    content,
+    /**
+     * This option gives us the control to enable the default behavior of rendering the editor immediately.
+     */
+    immediatelyRender: true,
+    /**
+     * This option gives us the control to disable the default behavior of re-rendering the editor on every transaction.
+     */
+    shouldRerenderOnTransaction: false,
+  })
+
+  const editorState = useEditorState({
+    editor,
+    // This function will be called every time the editor state changes
+    selector: (editorInstance: Editor) => ({
+      // It will only re-render if the bold or italic state changes
+      isBold: editorInstance.isActive('bold'),
+      isItalic: editorInstance.isActive('italic'),
+    }),
+    // This function will be used to compare the previous and the next state
+    equalityFn: deepEqual,
+  })
+
+  return (
+    <>
+      <EditorContent editor={editor} />
+      <button
+        onClick={() => editor.chain().focus().toggleBold().run()}
+        className={editorState.isBold ? 'primary' : ''}
+      >
+        Bold
+      </button>
+      <button
+        onClick={() => editor.chain().focus().toggleItalic().run()}
+        className={editorState.isItalic ? 'primary' : ''}
+      >
+        Italic
+      </button>
+    </>
+  )
+}
+```
 
 ## React NodeView Integration
 
-While NodeViews are supported, if you are using NodeViews in your editor, you should be aware that they can be expensive to render.
+While NodeViews with React are supported, if you are using them in your editor, you should be aware that they can be expensive to render.
 
-If you want the absolute best performance, your NodeViews should not be rendered by React. Instead you could use direct DOM manipulation to render them. This is because React is not optimized for rendering synchronously and NodeViews are expected to be rendered synchronously. This is especially important if you have a lot of NodeViews in your editor.
+If you want the absolute best performance, your NodeViews ideally would not be rendered by React. Instead you could use direct DOM manipulation to render them. This is because React is not optimized for rendering synchronously and NodeViews are expected to be rendered synchronously. This is especially important if you have several instances of NodeViews throughout your editor.