探索 Tiptap V3 的最新功能
Tiptap 中文文档

使用 Tiptap 转换 Markdown

Available in Start planBeta

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

  • 编辑器导入 – 将 .md 文件直接转换为 Tiptap JSON 以进行编辑器内编辑。
  • 编辑器导出 – 将 Tiptap 内容转换为 .md（标准 Markdown 或 GitHub 风格 Markdown）。
  • REST API – 通过 MD 转换 REST API 在服务器端集成 Markdown 转换，无需直接使用 Tiptap 编辑器。

编辑器 Markdown 导入

转换扩展发布在 Tiptap 的私有 npm 注册表中。按照 私有注册表指南 进行集成。

安装导入扩展：

npm i @tiptap-pro/extension-import

在您的编辑器中配置扩展 

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',
    }),
  ],
})

导入您的第一个文档 

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

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

自定义导入行为 

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()

选项

名称类型默认值描述
appIdstringundefined来自 https://cloud.tiptap.dev/convert-settings 的转换 App ID
tokenstringundefined在您的服务器上生成的JWT令牌
imageUploadCallbackUrlstringundefined如果未设置，Markdown中的图片可能作为外部链接处理或被省略（取决于文件结构）

命令

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

import 参数

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

编辑器 Markdown 导出

安装导出扩展： 

npm i @tiptap-pro/extension-export

在您的编辑器中配置扩展 

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

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

导出文档 

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

自定义导出行为 

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()

选项

名称类型默认值描述
appIdstringundefined来自 https://cloud.tiptap.dev/convert-settings 的转换 App ID
tokenstringundefined在您的服务器上生成的JWT令牌

命令

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

export 参数

名称类型默认值选项描述
formatstringundefineddocx,odt,md,gfm目标格式（此处为 md 或 gfm 表示 GitHub 风格 Markdown）
contentJSONContentundefined任何 Tiptap JSON可选：导出不同于当前编辑器内容的内容
onExportFunctionundefinedfn(context)自定义导出回调。接收一个包含 blob、潜在 error、download() 帮助函数和 filename 的上下文。可使用 blob.text() 获取原始文本