diff --git a/src/content/collaboration/documents/convert-api.mdx b/src/content/collaboration/documents/convert-api.mdx
new file mode 100644
index 0000000..89b8af4
--- /dev/null
+++ b/src/content/collaboration/documents/convert-api.mdx
@@ -0,0 +1,102 @@
+---
+title: Convert API Reference
+meta:
+ title: Convert API Reference | Tiptap Collaboration
+ description: Use Tiptap to convert documents from docx, odt or markdown to Tiptap
+ category: Collaboration
+---
+
+## Tiptap Editor extensions
+
+Instead of using the Convert API directly, you can use the Tiptap Editor extensions to import and export documents.
+
+- [Import Extension](/editor/extensions/functionality/import)
+- [Export Extension](/editor/extensions/functionality/export)
+
+## /import
+
+- **Method**: `POST`
+
+Convert a document to a Tiptap document.
+
+### Required headers
+
+| Name | Description |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Authorization` | The JWT token to authenticate the request. Example: `Bearer your-jwt-token` |
+| `X-App-Id` | The Convert App-ID from the Collaboration settings page: [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |
+
+### Body
+
+| Name | Type | Description |
+| ------ | ------ | ------------------- |
+| `file` | `File` | The file to convert |
+
+### Query parameters
+
+| Name | Default | Description |
+| ---------------- | ---------------- | -------------------------------------------------------------------- |
+| `paragraph` | `paragraph` | Defines which prosemirror type is used for paragraph conversion |
+| `heading` | `heading` | Defines which prosemirror type is used for heading conversion |
+| `blockquote` | `blockquote` | Defines which prosemirror type is used for blockquote conversion |
+| `codeblock` | `codeblock` | Defines which prosemirror type is used for codeblock conversion |
+| `bulletlist` | `bulletlist` | Defines which prosemirror type is used for bulletList conversion |
+| `orderedlist` | `orderedlist` | Defines which prosemirror type is used for orderedList conversion |
+| `listitem` | `listitem` | Defines which prosemirror type is used for listItem conversion |
+| `hardbreak` | `hardbreak` | Defines which prosemirror type is used for hardbreak conversion |
+| `horizontalrule` | `horizontalrule` | Defines which prosemirror type is used for horizontalRule conversion |
+| `table` | `table` | Defines which prosemirror type is used for table conversion |
+| `tablecell` | `tablecell` | Defines which prosemirror type is used for tableCell conversion |
+| `tableheader` | `tableheader` | Defines which prosemirror type is used for tableHeader conversion |
+| `tablerow` | `tablerow` | Defines which prosemirror type is used for tableRow conversion |
+| `bold` | `bold` | Defines which prosemirror mark is used for bold conversion |
+| `italic` | `italic` | Defines which prosemirror mark is used for italic conversion |
+| `underline` | `underline` | Defines which prosemirror mark is used for underline conversion |
+| `strikethrough` | `strike` | Defines which prosemirror mark is used for strikethrough conversion |
+| `link` | `link` | Defines which prosemirror mark is used for link conversion |
+| `code` | `code` | Defines which prosemirror mark is used for code conversion |
+
+## /export
+
+- **Method**: `POST`
+
+Convert a Tiptap document to a different format.
+
+### Required headers
+
+| Name | Description |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Authorization` | The JWT token to authenticate the request. Example: `Bearer your-jwt-token` |
+| `X-App-Id` | The Convert App-ID from the Collaboration settings page: [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |
+
+### Body
+
+| Name | Type | Description |
+| --------- | -------- | ------------------------------------------------------------ |
+| `content` | `Object` | The Tiptap document |
+| `format` | `string` | The format to convert to, can be `docx`, `odt` or `markdown` |
+
+### Query parameters
+
+| Name | Default | Description |
+| ---------------- | ---------------- | -------------------------------------------------------------------- |
+| `gfm` | `0` | Use Github Flavored Markdown for markdown export |
+| `paragraph` | `paragraph` | Defines which prosemirror type is used for paragraph conversion |
+| `heading` | `heading` | Defines which prosemirror type is used for heading conversion |
+| `blockquote` | `blockquote` | Defines which prosemirror type is used for blockquote conversion |
+| `codeblock` | `codeblock` | Defines which prosemirror type is used for codeblock conversion |
+| `bulletlist` | `bulletlist` | Defines which prosemirror type is used for bulletList conversion |
+| `orderedlist` | `orderedlist` | Defines which prosemirror type is used for orderedList conversion |
+| `listitem` | `listitem` | Defines which prosemirror type is used for listItem conversion |
+| `hardbreak` | `hardbreak` | Defines which prosemirror type is used for hardbreak conversion |
+| `horizontalrule` | `horizontalrule` | Defines which prosemirror type is used for horizontalRule conversion |
+| `table` | `table` | Defines which prosemirror type is used for table conversion |
+| `tablecell` | `tablecell` | Defines which prosemirror type is used for tableCell conversion |
+| `tableheader` | `tableheader` | Defines which prosemirror type is used for tableHeader conversion |
+| `tablerow` | `tablerow` | Defines which prosemirror type is used for tableRow conversion |
+| `bold` | `bold` | Defines which prosemirror mark is used for bold conversion |
+| `italic` | `italic` | Defines which prosemirror mark is used for italic conversion |
+| `underline` | `underline` | Defines which prosemirror mark is used for underline conversion |
+| `strikethrough` | `strike` | Defines which prosemirror mark is used for strikethrough conversion |
+| `link` | `link` | Defines which prosemirror mark is used for link conversion |
+| `code` | `code` | Defines which prosemirror mark is used for code conversion |
diff --git a/src/content/collaboration/sidebar.ts b/src/content/collaboration/sidebar.ts
index 1916034..319764b 100644
--- a/src/content/collaboration/sidebar.ts
+++ b/src/content/collaboration/sidebar.ts
@@ -75,6 +75,11 @@ export const sidebarConfig: SidebarConfig = {
title: 'Inject content',
href: '/collaboration/documents/content-injection',
},
+ {
+ title: 'Convert API',
+ href: '/collaboration/documents/convert-api',
+ tags: ['Beta'],
+ },
],
},
{
diff --git a/src/content/editor/extensions/functionality/export.mdx b/src/content/editor/extensions/functionality/export.mdx
new file mode 100644
index 0000000..7ee0992
--- /dev/null
+++ b/src/content/editor/extensions/functionality/export.mdx
@@ -0,0 +1,188 @@
+---
+title: Export
+tags:
+ - type: pro
+ - type: new
+meta:
+ category: Editor
+extension:
+ name: Export
+ description: Export Tiptap content to docx, odt, or markdown.
+ type: extension
+ icon: Download
+ isPro: true
+ isNew: true
+ isBeta: true
+ isCloud: true
+---
+
+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.
+
+
+
+ This extension requires a valid subscription in an eligible plan and [access to our private registry](/guides/pro-extensions), set this up first.
+
+ **You need to be a business customer, to use the advanced extension.**
+
+
+
+## Example
+
+
+
+## Setup JWT authentication on your server
+
+JWT, or JSON Web Token, is a compact, URL-safe means of representing claims to be transferred between two parties. The information in a JWT is digitally signed using a cryptographic algorithm to ensure that the claims cannot be altered after the token is issued. This digital signature makes the JWT a reliable vehicle for secure information exchange in web applications, providing a method to authenticate and exchange information.
+
+### Create a static JWT for testing
+
+For testing purposes, you might not want to set up a complete backend system to generate JWTs. In such cases, using online tools like http://jwtbuilder.jamiekurtz.com/ can be a quick workaround. These tools allow you to create a JWT by inputting the necessary payload and signing it with a secret key.
+
+When using these tools, ensure that the "Key" field is replaced with the secret key from your [Collaboration settings](https://collab.tiptap.dev/apps/settings) page. You don’t need to change any other information.
+
+**Remember, this approach is only recommended for testing due to security risks associated with exposing your secret key.**
+
+### Generate JWTs server side
+
+For production-level applications, generating JWTs on the server side is a necessity to maintain security. Exposing your secret key in client-side code would compromise the security of your application. Here’s an example using NodeJS for creating JWTs server-side:
+
+```bash
+npm install jsonwebtoken
+```
+
+```js
+import jsonwebtoken from 'jsonwebtoken'
+
+const payload = {
+ // The payload contains claims like the user ID, which can be used to identify the user and their permissions.
+ userId: 'user123',
+}
+
+// The 'sign' method creates the JWT, with the payload and your secret key as inputs.
+const jwt = jsonwebtoken.sign(payload, 'your_secret_key_here')
+// The resulting JWT is used for authentication in API requests, ensuring secure access.
+// Important: Never expose your secret key in client-side code!
+```
+
+This JWT should be incorporated into API requests within the token field of your authentication provider, safeguarding user sessions and data access.
+
+To fully integrate JWT into your application, consider setting up a dedicated server or API endpoint, such as `GET /getConvertToken`. This endpoint would dynamically generate JWTs based on a secret stored securely on the server and user-specific information, like document access permissions.
+
+This setup not only increases security but also provides a scalable solution for managing user sessions and permissions in your collaborative application.
+
+Ensure the secret key is stored as an environment variable on the server, or define it directly in the server code. Avoid sending it from the client side.
+
+## Setting up the client-side
+
+Before we can start import & exporting documents, we need to set up the extension. The extension will handle all requests and responses to the convert API & will handle content insertions and downloads.
+
+### Installing the extension
+
+To use the convert extension, you need to install the `@tiptap-pro/extension-export` package:
+
+```bash
+npm i @tiptap-pro/extension-export
+```
+
+### Configure the extension
+
+```js
+// Start with importing the extension
+import { Export } from '@tiptap/extension-export'
+
+const editor = new Editor({
+ // ...
+ extensions: [
+ // ...
+ Export.Configure({
+ // The Convert App-ID from the Collaboration settings page: https://cloud.tiptap.dev/convert-settings
+ appId: 'your-app-id',
+
+ // The JWT token you generated in the previous step
+ token: 'your-jwt',
+ }),
+ ],
+})
+```
+
+## Export a document
+
+```js
+// Do a simple export to docx
+// Supported formats: docx, odt, md and gfm
+editor.chain().export({ format: 'docx' }).focus().run()
+```
+
+### Customize the export behavior
+
+```js
+// You can also use the onExport callback to customize the export behavior
+editor.chain().export({
+ format: 'docx',
+ onExport(context) {
+ const { blob, error, download, filename } = context
+
+ // add error handling
+ if (error) {
+ showErrorToast({ message: error.message })
+ }
+
+ // you can change the loading state of your application for example
+ isLoading = false
+
+ // you could modify the filename or handle the blob differently here
+ // but we will keep them as they are
+
+ // you can trigger a download directly by calling the download method
+ download()
+
+ // keep in mind that the download method will only work in the browser
+ // and if the blob and filename was changed before must be managed manually
+ },
+})
+```
+
+## Options
+
+| Name | Type | Default | Description |
+| ------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `appId` | `string` | `undefined` | The convert app ID from the Collaboration settings page: [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |
+| `token` | `string` | `undefined` | The JWT token generated from your server via secret |
+
+## Commands
+
+| Name | Description |
+| -------- | ------------------------- |
+| `export` | Export the editor content |
+
+### `export`
+
+#### Arguments
+
+| Name | Type | Default | Options | Description |
+| ---------- | ------------- | ----------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `format` | `string` | `undefined` | `docx,odt,md,gfm` | The format you want to export to |
+| `content` | `JSONContent` | `undefined` | Any Tiptap JSON | The Tiptap JSON content you want to export |
+| `onExport` | `Function` | `undefined` | `fn(context)` | A callback used to customize the export behavior. The context argument includes information about the blob, filename, errors and a `download` function to download the document directly |
+
+## Supported formats
+
+- `docx` - Microsoft Word, Google Docs, OpenOffice, LibreOffice and others
+- `odt` - OpenDocument Text format used by OpenOffice, LibreOffice and others
+- Commonmark `markdown` - Markdown format used by various editors and platforms
+- GFM `markdown` - GitHub Flavored Markdown used by GitHub
+
+## Caveats and limitations
+
+- **Custom Node exports** - Exporting custom nodes or marks is not supported as they can't be converted into other format structures
+- **Custom docx templates** - Currently it's not possible to use custom docx templates for exporting documents
+- **PDF import & export** - Exporting PDF files is not yet supported
+
+We're continuously working on improving the import & export extension, so if you have any feedback or feature requests, please let us know!
+
+## More information
+
+- [Convert API Reference](/collaboration/documents/convert-api)
diff --git a/src/content/editor/extensions/functionality/import.mdx b/src/content/editor/extensions/functionality/import.mdx
new file mode 100644
index 0000000..5f3c74a
--- /dev/null
+++ b/src/content/editor/extensions/functionality/import.mdx
@@ -0,0 +1,200 @@
+---
+title: Import
+tags:
+ - type: pro
+ - type: new
+meta:
+ category: Editor
+extension:
+ name: Import
+ description: Import documents from docx, odt, or markdown to Tiptap.
+ type: extension
+ icon: Upload
+ isPro: true
+ isNew: true
+ isBeta: true
+ isCloud: true
+---
+
+import { Callout } from '@/components/ui/Callout'
+import { CodeDemo } from '@/components/CodeDemo'
+
+Import documents from various formats like docx, odt, and markdown and convert them to Tiptap's JSON format.
+
+
+ This extension is accessible to anyone with a Tiptap account. To install the extension you need
+ access to our [private registry](/guides/pro-extensions), set this up first.
+
+
+## Example
+
+
+
+## Authenticate on your server
+
+JWT, or JSON Web Token, is a compact, URL-safe means of representing claims to be transferred between two parties. The information in a JWT is digitally signed using a cryptographic algorithm to ensure that the claims cannot be altered after the token is issued.
+
+
+ Make sure to use the Auth key from the [Convert
+ settings](https://cloud.tiptap.dev/convert-settings) page. Other Tiptap feature authentications
+ cannot be used.
+
+
+### Create a static JWT for testing
+
+For testing purposes, you might not want to set up a complete backend system to generate JWTs. In such cases, using online tools like http://jwtbuilder.jamiekurtz.com/ can be a quick workaround. These tools allow you to create a JWT by inputting the necessary payload and signing it with a secret key.
+
+When using these tools, ensure that the "Key" field is replaced with the secret key from your [Convert settings](https://cloud.tiptap.dev/convert-settings) page. You don’t need to change any other information.
+
+
+ Remember, this approach is only recommended for testing due to security risks associated with
+ exposing your secret key.
+
+
+### Generate JWTs server side
+
+For production-level applications, generating JWTs on the server side is a necessity to maintain security. Exposing your secret key in client-side code would compromise the security of your application. Here’s an example using NodeJS for creating JWTs server-side:
+
+```bash
+npm install jsonwebtoken
+```
+
+```js
+import jsonwebtoken from 'jsonwebtoken'
+
+const payload = {
+ // The payload contains claims like the user ID, which can be used to identify the user and their permissions.
+ userId: 'user123',
+}
+
+// The 'sign' method creates the JWT, with the payload and your secret key as inputs.
+const jwt = jsonwebtoken.sign(payload, 'your_secret_key_here')
+// The resulting JWT is used for authentication in API requests, ensuring secure access.
+// Important: Never expose your secret key in client-side code!
+```
+
+This JWT should be incorporated into API requests within the token field of your authentication provider, safeguarding user sessions and data access.
+
+To fully integrate JWT into your application, consider setting up a dedicated server or API endpoint, such as `GET /getConvertToken`. This endpoint would dynamically generate JWTs based on a secret stored securely on the server and user-specific information, like document access permissions.
+
+This setup not only increases security but also provides a scalable solution for managing user sessions and permissions in your collaborative application.
+
+Ensure the secret key is stored as an environment variable on the server, or define it directly in the server code. Avoid sending it from the client side.
+
+## Set up the client-side
+
+Before we can start import & exporting documents, we need to set up the extension. The extension will handle all requests and responses to the convert API & will handle content insertions and downloads.
+
+### Install the extension
+
+To use the convert extension, you need to install the `@tiptap-pro/extension-import` package:
+
+```bash
+npm i @tiptap-pro/extension-import
+```
+
+### Configure the extension
+
+```js
+// Start with importing the extension
+import { Import } from '@tiptap/extension-import'
+
+const editor = new Editor({
+ // ...
+ extensions: [
+ // ...
+ Import.Configure({
+ // The Convert App-ID from the Collaboration settings page: https://cloud.tiptap.dev/convert-settings
+ appId: 'your-app-id',
+
+ // The JWT token you generated in the previous step
+ token: 'your-jwt',
+ }),
+ ],
+})
+```
+
+## Import your first document
+
+```js
+// 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()
+```
+
+### Customize the import behavior
+
+```js
+// You can also use the onImport callback to customize the import behavior
+editor
+ .chain()
+ .import({
+ file,
+ onImport(context) {
+ const { setEditorContent, content, error } = context
+
+ // add error handling
+ if (error) {
+ showErrorToast({ message: error.message })
+ }
+
+ // You could also modify the content before inserting it
+ content.doc.content.push({ type: 'paragraph', content: [{ type: 'text', text: 'Hello!' }] })
+
+ // you can change the loading state of your application for example
+ isLoading = false
+
+ // make sure you call the setEditorContent function if you want to run
+ // the default insertion behavior of the extension
+ // setEditorContent()
+ // but since we modified the content, we need to do the insertion manually
+ editor.commands.setContent(content)
+ },
+ })
+ .focus()
+ .run()
+```
+
+## Options
+
+| Name | Type | Default | Description |
+| ------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `appId` | `string` | `undefined` | The convert app ID from the Collaboration settings page: [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |
+| `token` | `string` | `undefined` | The JWT token generated from your server via secret |
+
+## Commands
+
+| Name | Description |
+| -------- | ----------------------------- |
+| `import` | Import a file into the editor |
+
+### `import`
+
+#### Arguments
+
+| Name | Type | Default | Options | Description |
+| ---------- | ---------- | ----------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `file` | `File` | `undefined` | Any file | The file to import |
+| `format` | `string` | `undefined` | `gfm` | Is used for special cases where the format is not clear, for example markdown gfm |
+| `onImport` | `Function` | `undefined` | `fn(context)` | A callback used to customize the import behavior. The context argument includes information about the content, errors and a `setEditorContent` function to modify the content |
+
+## Supported formats
+
+- `docx` - Microsoft Word, Google Docs, OpenOffice, LibreOffice and others
+- `odt` - OpenDocument Text format used by OpenOffice, LibreOffice and others
+- `rtf` - Rich Text Format used by Microsoft Word, Google Docs and others
+- Commonmark `markdown` - Markdown format used by various editors and platforms
+- GFM `markdown` - GitHub Flavored Markdown used by GitHub
+
+## Caveats and limitations
+
+- **Unsupported docx elements on import** - Importing docx files currently does not support page breaks, page headers and footers, horizontal rules or text styles
+- **Content added via suggestion mode** - Content added via suggestion mode is not included in the imported prosemirror document
+- **PDF import & export** - Importing and PDF files is not yet supported
+
+We're continuously working on improving the import & export extension, so if you have any feedback or feature requests, please let us know!
+
+## More information
+
+- [Convert API Reference](/collaboration/documents/convert-api)
diff --git a/src/content/editor/sidebar.ts b/src/content/editor/sidebar.ts
index b19ee05..4551fa6 100644
--- a/src/content/editor/sidebar.ts
+++ b/src/content/editor/sidebar.ts
@@ -279,6 +279,11 @@ export const sidebarConfig: SidebarConfig = {
href: '/editor/extensions/functionality/dropcursor',
title: 'Dropcursor',
},
+ {
+ href: '/editor/extensions/functionality/export',
+ title: 'Export',
+ tags: ['Beta', 'Pro'],
+ },
{
href: '/editor/extensions/functionality/filehandler',
title: 'File handler',
@@ -314,6 +319,11 @@ export const sidebarConfig: SidebarConfig = {
href: '/editor/extensions/functionality/listkeymap',
title: 'List Keymap',
},
+ {
+ href: '/editor/extensions/functionality/import',
+ title: 'Import',
+ tags: ['Beta', 'Pro'],
+ },
{
href: '/editor/extensions/functionality/mathematics',
title: 'Mathematics',