---
title: "使用 Tiptap 转换 Markdown（传统）"
description: "学习如何在 Tiptap 编辑器中使用传统的导入/导出扩展来处理 Markdown 文件。"
canonical_url: "https://tiptap.zhcndoc.com/conversion/legacy/markdown/editor-extensions"
---

# 使用 Tiptap 转换 Markdown（传统）

学习如何在 Tiptap 编辑器中使用传统的导入/导出扩展来处理 Markdown 文件。

> **旧版 Markdown 编辑器扩展（已弃用）:**
>
> 这些编辑器扩展已被弃用，并将在 2026 年的某个时间点停止支持，团队会提前通知。对于新的集成，请使用更新后的 [Markdown 导出扩展](https://tiptap.zhcndoc.com/conversion/export/markdown/editor-extension.md) 和 [导入 REST API](https://tiptap.zhcndoc.com/conversion/import/markdown/rest-api.md)。

Tiptap 的转换工具支持以三种方式处理 **Markdown** (`.md`) 文件：

- **编辑器导入** – 将 `.md` 文件直接转换为 Tiptap JSON 以进行编辑器内编辑。
- **编辑器导出** – 将 Tiptap 内容转换为 `.md`（标准 Markdown 或 GitHub 风格 Markdown）。
- **REST API** – 通过 [MD 转换 REST API](https://tiptap.zhcndoc.com/conversion/legacy/markdown/rest-api.md) 在服务器端集成 Markdown 转换，无需直接使用 Tiptap 编辑器。

* **1. 激活试用或订阅**

  在您的账户中[开始免费试用](https://cloud.tiptap.dev/v2?trial=true) 或者[订阅 Start 计划](https://cloud.tiptap.dev/v2/billing)。
* **2. 通过私有注册表安装**

  按照[设置指南](https://tiptap.zhcndoc.com/guides/pro-extensions.md)，通过验证登录 Tiptap 的私有 npm 注册表，安装此前端扩展。

## 编辑器 Markdown 导入

转换扩展发布在 Tiptap 的私有 npm 注册表中。可参考 [私有注册表指南](https://tiptap.zhcndoc.com/guides/pro-extensions.md) 进行集成。

**安装导入扩展：**

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

### 在您的编辑器中配置扩展

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

const editor = new Editor({
  // ...
  extensions: [
    // ...
    Import.configure({
      // 来自 https://cloud.tiptap.dev/convert-settings 的转换应用ID
      appId: 'your-app-id',

      // 您生成的JWT令牌
      token: 'your-jwt',

      // 如果您的Markdown中包含图片，可以提供图片上传的URL
      imageUploadCallbackUrl: 'https://your-image-upload-url.com',
    }),
  ],
})
```

### 导入您的第一个文档

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

此操作会将所选的 `.md` 文件上传到转换 API，将其转换为 Tiptap JSON，并替换当前编辑器内容。

### 自定义导入行为

```js
editor.chain().import({
  file,
  onImport(context) {
    const { setEditorContent, content, error } = context
    if (error) {
      showErrorToast({ message: error.message })
    }
    // 示例：在插入前添加一个段落
    content.doc.content.push({ type: 'paragraph', content: [{ type: 'text', text: '你好！' }] })
    isLoading = false
    editor.commands.setContent(content)
  },
}).focus().run()
```

### 选项

| 名称                       | 类型       | 默认值         | 描述                                                                                                   |
| ------------------------ | -------- | ----------- | ---------------------------------------------------------------------------------------------------- |
| `appId`                  | `string` | `undefined` | 来自 [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) 的转换 App ID |
| `token`                  | `string` | `undefined` | 在您的服务器上生成的 JWT 令牌                                                                                    |
| `imageUploadCallbackUrl` | `string` | `undefined` | 若未设置，Markdown 中的图片可能被当作外部链接处理或被省略（取决于文件结构）                                                           |

### 命令

| 命令       | 描述         |
| -------- | ---------- |
| `import` | 导入文件到编辑器内容 |

### `import` 参数

| 名称         | 类型         | 默认值         | 选项            | 描述                                                                            |
| ---------- | ---------- | ----------- | ------------- | ----------------------------------------------------------------------------- |
| `file`     | `File`     | `undefined` | 任何文件          | 要导入的文件                                                                        |
| `format`   | `string`   | `undefined` | `gfm`（可选）     | 若设为 `gfm`，转换将把输入视为 GitHub 风格 Markdown                                         |
| `onImport` | `Function` | `undefined` | `fn(context)` | 自定义导入的回调。接收一个包含 Tiptap JSON `content`、任何 `error` 和 `setEditorContent()` 的上下文。 |

## 编辑器 Markdown 导出

### 安装导出扩展：

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

### 在您的编辑器中配置扩展

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

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

### 导出文档

```js
// 将编辑器内容导出为 markdown
// 支持的导出格式：docx, odt, md, gfm
editor.chain().focus().export({ format: 'md' }).run()
```

### 自定义导出行为

```js
editor.chain().export({
  format: 'md',
  onExport(context) {
    const { blob, error, download, filename } = context
    if (error) {
      showErrorToast({ message: error.message })
    }
    isLoading = false
    // 如有需要，可重命名文件，处理blob，或调用download()
    download() // 在浏览器中触发“document.md”下载
  },
}).run()
```

### 选项

| 名称      | 类型       | 默认值         | 描述                                                                                   |
| ------- | -------- | ----------- | ------------------------------------------------------------------------------------ |
| `appId` | `string` | `undefined` | 来自 [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/) 的转换 App ID |
| `token` | `string` | `undefined` | 在您的服务器上生成的JWT令牌                                                                      |

### 命令

| 命令       | 描述       |
| -------- | -------- |
| `export` | 导出编辑器内容。 |

### `export` 参数

| 名称         | 类型            | 默认值         | 选项                | 描述                                                                                           |
| ---------- | ------------- | ----------- | ----------------- | -------------------------------------------------------------------------------------------- |
| `format`   | `string`      | `undefined` | `docx,odt,md,gfm` | 目标格式（此处 `md` 或 `gfm` 表示 GitHub 风格 Markdown）。                                                 |
| `content`  | `JSONContent` | `undefined` | 任何 Tiptap JSON    | 可选：导出与当前编辑器内容不同的内容                                                                           |
| `onExport` | `Function`    | `undefined` | `fn(context)`     | 自定义导出回调。接收包含 `blob`、可能的 `error`、`download()` 辅助函数和 `filename` 的上下文。可使用 `blob.text()` 获取原始文本。 |