Document conversion API

The document conversion API supports DOCX, ODT, and Markdown conversion from and to Tiptap’s JSON format.

The following demo uses the Document Conversion API by integrating both the import and export extensions into the editor.

Integrate into the editor

Tiptap offers editor extensions for importing and exporting documents. These extensions provide full access to the Document Conversion API. Instead of using the Document Conversion API directly, you can use Tiptap Editor's import and export extensions:

• Editor Import Extension
• Editor Export Extension

/import endpoint

The /import endpoint enables the conversion of docx, odt, or markdown files into Tiptap’s JSON format. Users can POST documents to this endpoint and use various parameters to customize how different document elements are handled during the conversion process.

• Method: POST

Required headers

Body

Query parameters

Specify how source document elements are mapped to ProseMirror nodes or marks, and adjust the conversion to meet your specific styling and structural preferences.

/import-docx endpoint (experimental)

The /import-docx endpoint enables the conversion of docx files into Tiptap's JSON format and allows for more docx-specific functions than the /import endpoint. Users can POST documents to this endpoint and use various parameters to customize how different document elements are handled during the conversion process.

• Method: POST

Required headers

Body

Query parameters

Specify how source document elements are mapped to ProseMirror nodes or marks, and adjust the conversion to meet your specific styling and structural preferences.

/export endpoint

The /export endpoint converts Tiptap documents back into formats like docx, odt, or markdown.

• Method: POST

Convert a Tiptap document to a different format.

Required headers

Body

Query parameters

Image Uploading

When converting documents, some formats may include images that you may want to preserve in the converted document. To do this, you can provide the optional imageUploadCallbackUrl parameter in the request body. This parameter should be a URL that the Convert service can use to upload images found in the document.

The Convert service will make a POST request to the provided URL with the image file as the request body. The response should be a JSON object with a url key containing the URL where the image was uploaded.

Tips

• The image upload callback URL should be a publicly accessible endpoint.
• The image upload callback URL should return a JSON object with a url key containing the URL where the image was uploaded.
• You can use any callback URL, so if you want to limit uploads, you can provide a URL that includes an API key or other authentication method.
• The URL you provide, will be written into the document as the image source, so make sure it is accessible to anyone who will view the document.

Server Implementation Example

This example shows a simple server implementation that accepts image uploads & uploads them to an S3 bucket configured by environment variables.

import { serve } from '@hono/node-server'
import { Hono } from 'hono'
import { Upload } from '@aws-sdk/lib-storage'
import { S3Client } from '@aws-sdk/client-s3'

const {
  AWS_ACCESS_KEY_ID,
  AWS_SECRET_ACCESS_KEY,
  AWS_REGION,
  AWS_S3_BUCKET,
  PORT = '3011',
  AWS_ENDPOINT,
  AWS_FORCE_STYLE,
} = process.env

if (!AWS_ACCESS_KEY_ID || !AWS_SECRET_ACCESS_KEY || !AWS_S3_BUCKET) {
  console.error('Please provide AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_S3_BUCKET')
  process.exit(1)
}

const s3 = new S3Client({
  credentials: {
    accessKeyId: AWS_ACCESS_KEY_ID,
    secretAccessKey: AWS_SECRET_ACCESS_KEY,
  },

  region: AWS_REGION,
  endpoint: AWS_ENDPOINT,
  forcePathStyle: AWS_FORCE_STYLE === 'true',
})

const app = new Hono() as Hono<any>

app.post('/upload', async (c) => {
  const body = await c.req.parseBody()
  const file = body['file']

  if (!file || typeof file === 'string') {
    return c.json({ error: 'No file uploaded' }, 400)
  }

  try {
    const data = await new Upload({
      client: s3,
      params: {
        Bucket: AWS_S3_BUCKET,
        // file.name is just current timestamp & file extension
        Key: file.name,
        Body: file,
        ContentType: file.type,
      },
    }).done()

    return c.json({ url: data.Location })
  } catch (error) {
    console.error(error)
    return c.json({ error: 'Failed to upload file' }, 500)
  }
})

serve({
  fetch: app.fetch,
  port: Number(PORT) || 3000,
})