---
title: "Convert Markdown with Tiptap (Legacy)"
description: "Learn how to handle Markdown files in a Tiptap editor using the legacy import/export extensions."
canonical_url: "https://tiptap.dev/docs/conversion/legacy/markdown/editor-extensions"
---

# Convert Markdown with Tiptap (Legacy)

Learn how to handle Markdown files in a Tiptap editor using the legacy import/export extensions.

> **Legacy Markdown Editor Extensions (Deprecated):**
>
> These editor extensions are deprecated and will be sunset at some point in 2026 with prior communication from the team. For new integrations, use the updated [Markdown export extensions](https://tiptap.dev/docs/conversion/export/markdown/editor-extension.md) and [import REST API](https://tiptap.dev/docs/conversion/import/markdown/rest-api.md).

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](https://tiptap.dev/docs/conversion/legacy/markdown/rest-api.md), without using the Tiptap editor directly.

* **1. Activate trial or subscribe**

  Start a [free trial](https://cloud.tiptap.dev/v2?trial=true) or [subscribe to the Start plan](https://cloud.tiptap.dev/v2/billing) in your account.
* **2. Install from private registry**

  To install this frontend extensions, authenticate to Tiptap's private npm registry by following the [setup guide](https://tiptap.dev/docs/guides/pro-extensions.md).

## Editor Markdown Import

The Conversion extensions are published in Tiptap's private npm registry. Integrate the extensions by following the [private registry guide](https://tiptap.dev/docs/guides/pro-extensions.md).

**Install the Import extension:**

```bash
npm i @tiptap-pro/extension-import
```

### Configure the extension in your editor

```js
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 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

```js
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

```js
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

| Name                     | Type     | Default     | Description                                                                                                    |
| ------------------------ | -------- | ----------- | -------------------------------------------------------------------------------------------------------------- |
| `appId`                  | `string` | `undefined` | Convert App ID from [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings)     |
| `token`                  | `string` | `undefined` | JWT generated on your server                                                                                   |
| `imageUploadCallbackUrl` | `string` | `undefined` | If not set, images in Markdown may be handled as external links or omitted (depending on the file's structure) |

### Commands

| Command  | Description                           |
| -------- | ------------------------------------- |
| `import` | Import a file into the editor content |

### `import` arguments

| Name       | Type       | Default     | Options          | Description                                                                                                             |
| ---------- | ---------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `file`     | `File`     | `undefined` | Any file         | The file to import                                                                                                      |
| `format`   | `string`   | `undefined` | `gfm` (optional) | If set to `gfm`, the conversion treats the input as GitHub Flavored Markdown                                            |
| `onImport` | `Function` | `undefined` | `fn(context)`    | Callback to customize import. Receives a context with the Tiptap JSON `content`, any `error`, and `setEditorContent()`. |

## Editor Markdown Export

### Install the Export extension:

```bash
npm i @tiptap-pro/extension-export
```

### Configure the extension in your editor

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

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

### Export a document

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

```js
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

| Name    | Type     | Default     | Description                                                                                |
| ------- | -------- | ----------- | ------------------------------------------------------------------------------------------ |
| `appId` | `string` | `undefined` | Convert App ID from [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/) |
| `token` | `string` | `undefined` | JWT generated from your server                                                             |

### Commands

| Command  | Description                |
| -------- | -------------------------- |
| `export` | Export the editor content. |

### `export` arguments

| Name       | Type          | Default     | Options           | Description                                                                                                                                            |
| ---------- | ------------- | ----------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `format`   | `string`      | `undefined` | `docx,odt,md,gfm` | The target format (here, `md` or `gfm` for GitHub Flavored Markdown).                                                                                  |
| `content`  | `JSONContent` | `undefined` | Any Tiptap JSON   | Optional: Export different content than what's currently in the editor.                                                                                |
| `onExport` | `Function`    | `undefined` | `fn(context)`     | Callback to customize the export. Receives a `blob`, potential `error`, a `download()` helper, and `filename`. Use `blob.text()` if you want raw text. |