From e60da03a04395eea9b2df36ee11bbbafb42adbd8 Mon Sep 17 00:00:00 2001 From: Dominik Biedebach Date: Fri, 12 Jul 2024 15:32:34 +0200 Subject: [PATCH 1/7] prepare convert docs --- .../collaboration/documents/convert/api.mdx | 81 ++++++++++ .../collaboration/documents/convert/index.mdx | 152 ++++++++++++++++++ src/content/collaboration/sidebar.ts | 10 ++ 3 files changed, 243 insertions(+) create mode 100644 src/content/collaboration/documents/convert/api.mdx create mode 100644 src/content/collaboration/documents/convert/index.mdx diff --git a/src/content/collaboration/documents/convert/api.mdx b/src/content/collaboration/documents/convert/api.mdx new file mode 100644 index 0000000..c692628 --- /dev/null +++ b/src/content/collaboration/documents/convert/api.mdx @@ -0,0 +1,81 @@ +--- +title: API Reference +meta: + title: Convert API Reference | Tiptap Collaboration + description: Use Tiptap to convert documents from docx, odt or markdown to Tiptap + category: Collaboration +--- + +## /import + +- **Method**: `POST` + +Convert a document to a Tiptap document. + +### 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. + +### 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/documents/convert/index.mdx b/src/content/collaboration/documents/convert/index.mdx new file mode 100644 index 0000000..4a79f2e --- /dev/null +++ b/src/content/collaboration/documents/convert/index.mdx @@ -0,0 +1,152 @@ +--- +title: Convert documents with Tiptap +meta: + title: Convert | Tiptap Collaboration + description: Use Tiptap to convert documents from docx, odt or markdown to Tiptap + category: Collaboration +--- + +With Tiptap Convert, you can easily import and export documents from various formats like docx, odt, and markdown. This feature allows you to convert documents to and from Tiptap's JSON format, enabling seamless integration with your collaborative editor. + +## 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 + +Before we can start converting documents, we need to set up the client. The client is responsible for sending requests to the server to convert documents. The client needs to be authenticated with a JWT token to access the conversion service. + +### Installing the client + +To make working with the converter easier, you can use the `@tiptap/convert` package. This package provides a simple API to import and export documents. + +```bash +npm i @tiptap/convert +``` + +### Creating the client & adding authentication + +```js +// Start with importing the client into your project +import { createClient } from '@tiptap/convert' + +// Create a new client instance +// use a generated client JWT token to authenticate your client +// see the JWT generation guide above +const convertClient = createClient({ + appId: 'YOUR_APP_ID', + token: 'CLIENT_JWT_TOKEN', +}) + +// export your convert client for later use +export default convertClient +``` + +### Importing your first document and modifiying the editor + +```js +// Import your convert client +import convertClient from './convertClient' + +// Handle a file upload +const handleFileUpload = async (event) => { + const file = event.target.files[0] // lets pick the file out of the form event + + try { + // Convert the file to a Tiptap document + const tiptapDocument = await convertClient.import({ file, format: 'docx' }) + + // Now you can use the tiptapDocument in your editor + editor.chain().setContent(tiptapDocument).run() + } catch (e) { + // add your custom error handling + console.error(e) + } +} +``` + +### Exporting a document + +```js +// import your convert client +import convertClient from './convertClient' + +const handleDocxExport = async () => { + try { + // Convert the Tiptap document to a docx file + const docxFile = await convertClient.export({ content: editor.getJSON(), format: 'docx' }) + + // Now you can download the docx file by creating a link containing the file's object url + const url = URL.createObjectURL(docxFile) + const link = document.createElement('a') + link.href = url + link.download = 'document.docx' + link.click() + + // remember to remove the unused element from the DOM + link.remove() + } catch (e) { + // add your custom error handling + console.error(e) + } +} +``` + +## Supported formats + +### Import + +- `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 + +### Export + +- `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 + +## More information + +- [API Reference](/collaboration/documents/convert/api) diff --git a/src/content/collaboration/sidebar.ts b/src/content/collaboration/sidebar.ts index 1916034..6b62524 100644 --- a/src/content/collaboration/sidebar.ts +++ b/src/content/collaboration/sidebar.ts @@ -75,6 +75,16 @@ export const sidebarConfig: SidebarConfig = { title: 'Inject content', href: '/collaboration/documents/content-injection', }, + { + title: 'Import and export', + href: '/collaboration/documents/convert', + children: [ + { + title: 'API Reference', + href: '/collaboration/documents/convert/api', + }, + ], + }, ], }, { From e3f13ccb617fa80e24db11732d6c0c7f31e1c527 Mon Sep 17 00:00:00 2001 From: Dominik Biedebach Date: Mon, 15 Jul 2024 09:57:07 +0200 Subject: [PATCH 2/7] docs(import-export): add exaples and new import-export api --- .../{convert => import-export}/api.mdx | 16 +- .../documents/import-export/extension-api.mdx | 41 +++++ .../{convert => import-export}/index.mdx | 172 +++++++++++------- src/content/collaboration/sidebar.ts | 8 +- 4 files changed, 172 insertions(+), 65 deletions(-) rename src/content/collaboration/documents/{convert => import-export}/api.mdx (80%) create mode 100644 src/content/collaboration/documents/import-export/extension-api.mdx rename src/content/collaboration/documents/{convert => import-export}/index.mdx (51%) diff --git a/src/content/collaboration/documents/convert/api.mdx b/src/content/collaboration/documents/import-export/api.mdx similarity index 80% rename from src/content/collaboration/documents/convert/api.mdx rename to src/content/collaboration/documents/import-export/api.mdx index c692628..2505f28 100644 --- a/src/content/collaboration/documents/convert/api.mdx +++ b/src/content/collaboration/documents/import-export/api.mdx @@ -1,5 +1,5 @@ --- -title: API Reference +title: Import & Export API Reference meta: title: Convert API Reference | Tiptap Collaboration description: Use Tiptap to convert documents from docx, odt or markdown to Tiptap @@ -12,6 +12,13 @@ meta: 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 | @@ -48,6 +55,13 @@ Convert a document to a Tiptap document. 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 | diff --git a/src/content/collaboration/documents/import-export/extension-api.mdx b/src/content/collaboration/documents/import-export/extension-api.mdx new file mode 100644 index 0000000..a53edcf --- /dev/null +++ b/src/content/collaboration/documents/import-export/extension-api.mdx @@ -0,0 +1,41 @@ +--- +title: Import & Export Extension API +meta: + title: Import & Export Extension API Reference | Tiptap Collaboration + description: Use Tiptap to convert documents from docx, odt or markdown to Tiptap + category: Collaboration +--- + +## 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 | +| `export` | Export the editor content | + +### `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 | + +### `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 | diff --git a/src/content/collaboration/documents/convert/index.mdx b/src/content/collaboration/documents/import-export/index.mdx similarity index 51% rename from src/content/collaboration/documents/convert/index.mdx rename to src/content/collaboration/documents/import-export/index.mdx index 4a79f2e..132dfae 100644 --- a/src/content/collaboration/documents/convert/index.mdx +++ b/src/content/collaboration/documents/import-export/index.mdx @@ -1,13 +1,28 @@ --- -title: Convert documents with Tiptap +title: Import & Export documents with Tiptap meta: - title: Convert | Tiptap Collaboration - description: Use Tiptap to convert documents from docx, odt or markdown to Tiptap + title: Import & export | Tiptap Collaboration + description: Use Tiptap to import & export documents from docx, odt or markdown to Tiptap category: Collaboration --- +import { Callout } from '@/components/ui/Callout' +import { CodeDemo } from '@/components/CodeDemo' + + + + 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.** + + + With Tiptap Convert, you can easily import and export documents from various formats like docx, odt, and markdown. This feature allows you to convert documents to and from Tiptap's JSON format, enabling seamless integration with your collaborative editor. +## 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. @@ -50,84 +65,116 @@ This setup not only increases security but also provides a scalable solution for 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 +## Setting up the client-side -Before we can start converting documents, we need to set up the client. The client is responsible for sending requests to the server to convert documents. The client needs to be authenticated with a JWT token to access the conversion service. +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 client +### Installing the extension -To make working with the converter easier, you can use the `@tiptap/convert` package. This package provides a simple API to import and export documents. +To use the convert extension, you need to install the `@tiptap-pro/extension-import-export` package: ```bash -npm i @tiptap/convert +npm i @tiptap-pro/extension-import-export ``` -### Creating the client & adding authentication +### Configure the extension ```js -// Start with importing the client into your project -import { createClient } from '@tiptap/convert' - -// Create a new client instance -// use a generated client JWT token to authenticate your client -// see the JWT generation guide above -const convertClient = createClient({ - appId: 'YOUR_APP_ID', - token: 'CLIENT_JWT_TOKEN', +// Start with importing the extension +import { ImportExport } from '@tiptap/extension-import-export' + +const editor = new Editor({ + // ... + extensions: [ + // ... + ImportExport.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', + }), + ], }) +``` + +## Importing your first document -// export your convert client for later use -export default convertClient +```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() ``` -### Importing your first document and modifiying the editor +### Customize the import behavior ```js -// Import your convert client -import convertClient from './convertClient' - -// Handle a file upload -const handleFileUpload = async (event) => { - const file = event.target.files[0] // lets pick the file out of the form event - - try { - // Convert the file to a Tiptap document - const tiptapDocument = await convertClient.import({ file, format: 'docx' }) - - // Now you can use the tiptapDocument in your editor - editor.chain().setContent(tiptapDocument).run() - } catch (e) { - // add your custom error handling - console.error(e) - } -} +// 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() ``` ### Exporting a document ```js -// import your convert client -import convertClient from './convertClient' - -const handleDocxExport = async () => { - try { - // Convert the Tiptap document to a docx file - const docxFile = await convertClient.export({ content: editor.getJSON(), format: 'docx' }) - - // Now you can download the docx file by creating a link containing the file's object url - const url = URL.createObjectURL(docxFile) - const link = document.createElement('a') - link.href = url - link.download = 'document.docx' - link.click() - - // remember to remove the unused element from the DOM - link.remove() - } catch (e) { - // add your custom error handling - console.error(e) - } -} +// 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 + }, +}) ``` ## Supported formats @@ -149,4 +196,5 @@ const handleDocxExport = async () => { ## More information -- [API Reference](/collaboration/documents/convert/api) +- [Extension API](/collaboration/documents/import-export/extension-api) +- [API Reference](/collaboration/documents/import-export/api) diff --git a/src/content/collaboration/sidebar.ts b/src/content/collaboration/sidebar.ts index 6b62524..710419a 100644 --- a/src/content/collaboration/sidebar.ts +++ b/src/content/collaboration/sidebar.ts @@ -77,11 +77,15 @@ export const sidebarConfig: SidebarConfig = { }, { title: 'Import and export', - href: '/collaboration/documents/convert', + href: '/collaboration/documents/import-export', children: [ + { + title: 'Extension API Reference', + href: '/collaboration/documents/import-export/extension-api', + }, { title: 'API Reference', - href: '/collaboration/documents/convert/api', + href: '/collaboration/documents/import-export/api', }, ], }, From a979625e3f247f77e93a3cd117f127a0d48534ca Mon Sep 17 00:00:00 2001 From: Dominik Biedebach Date: Mon, 15 Jul 2024 10:06:06 +0200 Subject: [PATCH 3/7] added caveats and limitations to import-export docs --- .../collaboration/documents/import-export/index.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/content/collaboration/documents/import-export/index.mdx b/src/content/collaboration/documents/import-export/index.mdx index 132dfae..17364e9 100644 --- a/src/content/collaboration/documents/import-export/index.mdx +++ b/src/content/collaboration/documents/import-export/index.mdx @@ -194,6 +194,16 @@ editor.chain().export({ - 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 +- **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 +- **Custom docx templates** - Currently it's not possible to use custom docx templates for exporting documents +- **PDF import & export** - Importing and 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 - [Extension API](/collaboration/documents/import-export/extension-api) From 7f845661f03427cdd59dc1e11d798169354eda80 Mon Sep 17 00:00:00 2001 From: ThisDavidRichard <147505039+ThisDavidRichard@users.noreply.github.com> Date: Mon, 15 Jul 2024 10:45:33 +0200 Subject: [PATCH 4/7] Content changes --- .../documents/import-export/index.mdx | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/src/content/collaboration/documents/import-export/index.mdx b/src/content/collaboration/documents/import-export/index.mdx index 17364e9..b2af6b2 100644 --- a/src/content/collaboration/documents/import-export/index.mdx +++ b/src/content/collaboration/documents/import-export/index.mdx @@ -9,31 +9,31 @@ meta: import { Callout } from '@/components/ui/Callout' import { CodeDemo } from '@/components/CodeDemo' - - - 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.** +Import and export documents from various formats like docx, odt, and markdown and convert them to and from 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. -With Tiptap Convert, you can easily import and export documents from various formats like docx, odt, and markdown. This feature allows you to convert documents to and from Tiptap's JSON format, enabling seamless integration with your collaborative editor. - -## Example - -## Setup JWT authentication on your server +## 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. This digital signature makes the JWT a reliable vehicle for secure information exchange in web applications, providing a method to authenticate and exchange information. +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 [Collaboration settings](https://collab.tiptap.dev/apps/settings) page. You don’t need to change any other information. +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.** + + Remember, this approach is only recommended for testing due to security risks associated with exposing your secret key. + ### Generate JWTs server side @@ -65,11 +65,11 @@ This setup not only increases security but also provides a scalable solution for 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 +## 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. -### Installing the extension +### Install the extension To use the convert extension, you need to install the `@tiptap-pro/extension-import-export` package: @@ -98,7 +98,7 @@ const editor = new Editor({ }) ``` -## Importing your first document +## Import your first document ```js // The most simple way to import a file @@ -140,7 +140,7 @@ editor .run() ``` -### Exporting a document +### Export a document ```js // Do a simple export to docx From bed2af0709dc164b24ff0ba8e0d31e6697ab488b Mon Sep 17 00:00:00 2001 From: ThisDavidRichard <147505039+ThisDavidRichard@users.noreply.github.com> Date: Mon, 15 Jul 2024 11:30:26 +0200 Subject: [PATCH 5/7] Added beta flag to sidebar --- src/content/collaboration/sidebar.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/collaboration/sidebar.ts b/src/content/collaboration/sidebar.ts index 710419a..2184e63 100644 --- a/src/content/collaboration/sidebar.ts +++ b/src/content/collaboration/sidebar.ts @@ -78,6 +78,7 @@ export const sidebarConfig: SidebarConfig = { { title: 'Import and export', href: '/collaboration/documents/import-export', + tags: ['Beta'], children: [ { title: 'Extension API Reference', From 0ae8207f1d22783e725076c6a26cacf996d98455 Mon Sep 17 00:00:00 2001 From: Dominik Biedebach Date: Mon, 15 Jul 2024 15:57:38 +0200 Subject: [PATCH 6/7] move demos for convert around, add extension documentations --- .../api.mdx => convert-api.mdx} | 2 +- .../documents/import-export/extension-api.mdx | 41 ---- src/content/collaboration/sidebar.ts | 14 +- .../extensions/functionality/export.mdx | 187 ++++++++++++++++++ .../extensions/functionality/import.mdx} | 89 ++++----- src/content/editor/sidebar.ts | 10 + 6 files changed, 236 insertions(+), 107 deletions(-) rename src/content/collaboration/documents/{import-export/api.mdx => convert-api.mdx} (99%) delete mode 100644 src/content/collaboration/documents/import-export/extension-api.mdx create mode 100644 src/content/editor/extensions/functionality/export.mdx rename src/content/{collaboration/documents/import-export/index.mdx => editor/extensions/functionality/import.mdx} (67%) diff --git a/src/content/collaboration/documents/import-export/api.mdx b/src/content/collaboration/documents/convert-api.mdx similarity index 99% rename from src/content/collaboration/documents/import-export/api.mdx rename to src/content/collaboration/documents/convert-api.mdx index 2505f28..0c21bda 100644 --- a/src/content/collaboration/documents/import-export/api.mdx +++ b/src/content/collaboration/documents/convert-api.mdx @@ -1,5 +1,5 @@ --- -title: Import & Export API Reference +title: Convert API Reference meta: title: Convert API Reference | Tiptap Collaboration description: Use Tiptap to convert documents from docx, odt or markdown to Tiptap diff --git a/src/content/collaboration/documents/import-export/extension-api.mdx b/src/content/collaboration/documents/import-export/extension-api.mdx deleted file mode 100644 index a53edcf..0000000 --- a/src/content/collaboration/documents/import-export/extension-api.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Import & Export Extension API -meta: - title: Import & Export Extension API Reference | Tiptap Collaboration - description: Use Tiptap to convert documents from docx, odt or markdown to Tiptap - category: Collaboration ---- - -## 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 | -| `export` | Export the editor content | - -### `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 | - -### `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 | diff --git a/src/content/collaboration/sidebar.ts b/src/content/collaboration/sidebar.ts index 710419a..5056157 100644 --- a/src/content/collaboration/sidebar.ts +++ b/src/content/collaboration/sidebar.ts @@ -76,18 +76,8 @@ export const sidebarConfig: SidebarConfig = { href: '/collaboration/documents/content-injection', }, { - title: 'Import and export', - href: '/collaboration/documents/import-export', - children: [ - { - title: 'Extension API Reference', - href: '/collaboration/documents/import-export/extension-api', - }, - { - title: 'API Reference', - href: '/collaboration/documents/import-export/api', - }, - ], + title: 'Convert API', + href: '/collaboration/documents/convert-api', }, ], }, diff --git a/src/content/editor/extensions/functionality/export.mdx b/src/content/editor/extensions/functionality/export.mdx new file mode 100644 index 0000000..127c406 --- /dev/null +++ b/src/content/editor/extensions/functionality/export.mdx @@ -0,0 +1,187 @@ +--- +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 + isCloud: true +--- + +import { Callout } from '@/components/ui/Callout' +import { CodeDemo } from '@/components/CodeDemo' + + + + 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.** + + + +With Tiptap Convert, you can easily export documents to various formats like docx, odt, and markdown. This feature allows you to convert documents from Tiptap's JSON format, enabling seamless integration with your collaborative editor. + +## 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', + }), + ], +}) +``` + +## Exporting 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/collaboration/documents/import-export/index.mdx b/src/content/editor/extensions/functionality/import.mdx similarity index 67% rename from src/content/collaboration/documents/import-export/index.mdx rename to src/content/editor/extensions/functionality/import.mdx index 17364e9..ba0e068 100644 --- a/src/content/collaboration/documents/import-export/index.mdx +++ b/src/content/editor/extensions/functionality/import.mdx @@ -1,9 +1,18 @@ --- -title: Import & Export documents with Tiptap +title: Import +tags: + - type: pro + - type: new meta: - title: Import & export | Tiptap Collaboration - description: Use Tiptap to import & export documents from docx, odt or markdown to Tiptap - category: Collaboration + category: Editor +extension: + name: Import + description: Import documents from docx, odt, or markdown to Tiptap. + type: extension + icon: Upload + isPro: true + isNew: true + isCloud: true --- import { Callout } from '@/components/ui/Callout' @@ -17,7 +26,7 @@ import { CodeDemo } from '@/components/CodeDemo' -With Tiptap Convert, you can easily import and export documents from various formats like docx, odt, and markdown. This feature allows you to convert documents to and from Tiptap's JSON format, enabling seamless integration with your collaborative editor. +With Tiptap Convert, you can easily import documents from various formats like docx, odt, and markdown. This feature allows you to convert documents to Tiptap's JSON format, enabling seamless integration with your collaborative editor. ## Example @@ -71,23 +80,23 @@ Before we can start import & exporting documents, we need to set up the extensio ### Installing the extension -To use the convert extension, you need to install the `@tiptap-pro/extension-import-export` package: +To use the convert extension, you need to install the `@tiptap-pro/extension-import` package: ```bash -npm i @tiptap-pro/extension-import-export +npm i @tiptap-pro/extension-import ``` ### Configure the extension ```js // Start with importing the extension -import { ImportExport } from '@tiptap/extension-import-export' +import { Import } from '@tiptap/extension-import' const editor = new Editor({ // ... extensions: [ // ... - ImportExport.Configure({ + Import.Configure({ // The Convert App-ID from the Collaboration settings page: https://cloud.tiptap.dev/convert-settings appId: 'your-app-id', @@ -140,71 +149,45 @@ editor .run() ``` -### Exporting a document +## Options -```js -// Do a simple export to docx -// Supported formats: docx, odt, md and gfm -editor.chain().export({ format: 'docx' }).focus().run() -``` +| 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 | -### 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 +## Commands - // add error handling - if (error) { - showErrorToast({ message: error.message }) - } +| Name | Description | +| -------- | ----------------------------- | +| `import` | Import a file into the editor | - // you can change the loading state of your application for example - isLoading = false +### `import` - // you could modify the filename or handle the blob differently here - // but we will keep them as they are +#### Arguments - // 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 - }, -}) -``` +| 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 -### Import - - `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 -### Export - -- `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 - **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 -- **Custom docx templates** - Currently it's not possible to use custom docx templates for exporting documents -- **PDF import & export** - Importing and exporting PDF files is not yet supported +- **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 -- [Extension API](/collaboration/documents/import-export/extension-api) -- [API Reference](/collaboration/documents/import-export/api) +- [Convert API Reference](/collaboration/documents/convert-api) diff --git a/src/content/editor/sidebar.ts b/src/content/editor/sidebar.ts index b19ee05..a6d8e60 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: ['Pro', 'Cloud'], + }, { 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: ['Pro', 'Cloud'], + }, { href: '/editor/extensions/functionality/mathematics', title: 'Mathematics', From 0b90b2c1ba8bebb0456594c3b721de62f130768d Mon Sep 17 00:00:00 2001 From: Dominik Biedebach Date: Mon, 15 Jul 2024 16:23:42 +0200 Subject: [PATCH 7/7] chore: update documentation for convert API --- src/content/collaboration/documents/convert-api.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/content/collaboration/documents/convert-api.mdx b/src/content/collaboration/documents/convert-api.mdx index 0c21bda..89b8af4 100644 --- a/src/content/collaboration/documents/convert-api.mdx +++ b/src/content/collaboration/documents/convert-api.mdx @@ -6,6 +6,13 @@ meta: 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`