-
-
Notifications
You must be signed in to change notification settings - Fork 40
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #8 from ueberdosis/convert
Add documentation for Convert API and Import and Export extensions
- Loading branch information
Showing
5 changed files
with
505 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
|
|
||
| <Callout title="Pro Extension" variant="warning"> | ||
|
|
||
| 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.** | ||
|
|
||
| </Callout> | ||
|
|
||
| ## Example | ||
|
|
||
| <CodeDemo isPro path="/Extensions/ImportExport" /> | ||
|
|
||
| ## 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) |
Oops, something went wrong.