使用 Tiptap 转换 Markdown(传统)
Start 计划已弃用
旧版 Markdown 编辑器扩展(已弃用)
这些编辑器扩展已被弃用,并将在 2026 年的某个时间点停止支持,团队会提前通知。对于新的集成,请使用更新后的 Markdown 导出扩展 和 导入 REST API。
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()选项
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
appId | string | undefined | 来自 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 导出
安装导出扩展:
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()选项
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
appId | string | undefined | 来自 https://cloud.tiptap.dev/convert-settings 的转换 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() 获取原始文本。 |