Tiptap Docs

Convert markdown with Tiptap

Tiptap’s Conversion tools support handling Markdown (.md) files in three ways:

  • Editor Import – Convert .md files directly into Tiptap JSON for in-editor editing.
  • Editor Export – Convert Tiptap content into .md (either standard Markdown or GitHub Flavored Markdown).
  • REST API – Integrate markdown conversion on the server with the MD conversion REST API, without using the Tiptap editor directly.

Integrate or test Conversion

To test or integrate this feature you need an active trial or Tiptap subscription.

Editor Markdown Import

The Conversion extensions are published in Tiptap’s private npm registry. Integrate the extensions by following the private registry guide.

Install the Import extension:

npm i @tiptap-pro/extension-import

Configure the extension in your editor 

import { Import } from '@tiptap-pro/extension-import'

const editor = new Editor({
  // ...
  extensions: [
    // ...
    Import.configure({
      // Your Convert App ID from https://cloud.tiptap.dev/convert-settings
      appId: 'your-app-id',

      // JWT token you generated
      token: 'your-jwt',

      // If your markdown includes images, you can provide a URL for image upload
      imageUploadCallbackUrl: 'https://your-image-upload-url.com',
    }),
  ],
})

Import your first document 

editor.chain().focus().import({ file }).run()

This uploads the chosen .md file to the Conversion API, converts it into Tiptap JSON, and replaces the current editor content.

Customize the import behavior 

editor.chain().import({
  file,
  onImport(context) {
    const { setEditorContent, content, error } = context
    if (error) {
      showErrorToast({ message: error.message })
    }
    // Example: add a paragraph before insertion
    content.doc.content.push({ type: 'paragraph', content: [{ type: 'text', text: 'Hello!' }] })
    isLoading = false
    editor.commands.setContent(content)
  },
}).focus().run()

Options

NameTypeDefaultDescription
appIdstringundefinedConvert App ID from https://cloud.tiptap.dev/convert-settings
tokenstringundefinedJWT token generated on your server
imageUploadCallbackUrlstringundefinedIf not set, images in Markdown may be handled as external links or omitted (depending on the file’s structure)

Commands

CommandDescription
importImport a file into the editor content

import arguments

NameTypeDefaultOptionsDescription
fileFileundefinedAny fileThe file to import
formatstringundefinedgfm (optional)If set to gfm, the conversion treats the input as GitHub Flavored Markdown
onImportFunctionundefinedfn(context)Callback to customize import. Receives a context with the Tiptap JSON content, any error, and setEditorContent().

Editor Markdown Export

Install the Export extension: 

npm i @tiptap-pro/extension-export

Configure the extension in your editor 

import { Export } from '@tiptap-pro/extension-export'

const editor = new Editor({
  // ...
  extensions: [
    // ...
    Export.configure({
      appId: 'your-app-id',
      token: 'your-jwt',
    }),
  ],
})

Export a document 

// Export the editor's content as markdown
// Supported export formats: docx, odt, md, gfm
editor.chain().focus().export({ format: 'md' }).run()

Customize the export behavior 

editor.chain().export({
  format: 'md',
  onExport(context) {
    const { blob, error, download, filename } = context
    if (error) {
      showErrorToast({ message: error.message })
    }
    isLoading = false
    // If needed, rename the file, handle the blob, or call download()
    download() // triggers a "document.md" download in the browser
  },
}).run()

Options

NameTypeDefaultDescription
appIdstringundefinedConvert App ID from https://cloud.tiptap.dev/convert-settings
tokenstringundefinedJWT token generated from your server

Commands

CommandDescription
exportExport the editor content.

export arguments

NameTypeDefaultOptionsDescription
formatstringundefineddocx,odt,md,gfmThe target format (here, md or gfm for GitHub Flavored Markdown).
contentJSONContentundefinedAny Tiptap JSONOptional: Export different content than what's currently in the editor.
onExportFunctionundefinedfn(context)Callback to customize the export. Receives a blob, potential error, a download() helper, and filename. Use blob.text() if you want raw text.