Import

Import documents from various formats like docx, odt, and markdown and convert them to Tiptap's JSON format.

We also have an Export extension, or you can review an example that does both import and export over here.

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.

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 page. You don’t need to change any other information.

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:

npm install jsonwebtoken

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:

npm i @tiptap-pro/extension-import

Configure the extension

// Start with importing the extension
import { Import } from '@tiptap/extension-import'

const editor = new Editor({
  // ...
  extensions: [
    // ...
    Import.Configure({
      // The Convert App-ID from the Convert 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

// The most simple way to import a file
// This will import the uploaded file, replace the editor content
// and focus the editor
editor.chain().focus().import({ file }).run()

Customize the import behavior

// 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

Commands

import

Arguments

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
• Inline styles - Inline styles are currently not parsed and are not available in import & export

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

• Conversion API Reference