---
title: "通过 REST API 导出 Markdown"
description: "了解如何使用 Tiptap Conversion REST API v2 将 Tiptap JSON 文档导出为 Markdown 格式。"
canonical_url: "https://tiptap.zhcndoc.com/conversion/export/markdown/rest-api"
---

# 通过 REST API 导出 Markdown

了解如何使用 Tiptap Conversion REST API v2 将 Tiptap JSON 文档导出为 Markdown 格式。

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

  在您的账户中开始一个[免费试用](https://cloud.tiptap.dev/v2?trial=true)或[订阅入门计划](https://cloud.tiptap.dev/v2/billing)。
- **2. 配置 Convert 应用**

  使用携带 `aud: "Convert"` 的签名令牌对 REST 调用进行身份验证。请参见[身份验证](https://tiptap.zhcndoc.com/authentication.md)。

Markdown 导出 API 将 Tiptap JSON 文档转换为 Markdown 文件。

> **查看 Postman 集合:**
>
> 您也可以通过访问我们的[Postman
> 集合](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/collection/33042171-bcc93ecb-8bad-4484-8cb0-d995ee23ae60)来体验文档转换 API。

## 导出 Markdown

`POST /v2/convert/export/markdown`

`/v2/convert/export/markdown` 端点将 Tiptap JSON 文档转换为 Markdown 格式。发送带有文档 JSON 正文的 `POST` 请求，即可获得可下载的 Markdown 文件。

### 示例（cURL）

```bash
curl --output document.md -X POST "https://api.tiptap.dev/v2/convert/export/markdown" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"来自 Tiptap 的你好！\"}]}]}"
    }'
```

> **需要订阅:**
>
> 此端点需要有效的 Tiptap 订阅。详情请查看我们的[定价页面](https://tiptap.dev/pricing)。

### 必需头信息

| Name            | Description                               |
| --------------- | ----------------------------------------- |
| `Authorization` | 用于验证请求的 JWT 令牌。示例：`Bearer your-jwt-token` |
| `Content-Type`  | 必须为 `application/json`                    |

### 请求体

| 名称    | 类型       | 说明                       | 必需 |
| ----- | -------- | ------------------------ | -- |
| `doc` | `String` | 以字符串形式传入的 Tiptap JSON 文档 | 是  |

### 响应

成功时，API 返回一个文本下载的 Markdown 文件：

- **状态**：`200 OK`
- **Content-Type**：`text/markdown; charset=utf-8`
- **Content-Disposition**：`attachment; filename=export-{timestamp}.md`

### 错误响应

| Status | Code                            | Description   |
| ------ | ------------------------------- | ------------- |
| 400    | `NO_DOCUMENT_PROVIDED`          | 未在正文中提供文档     |
| 422    | `FAILED_TO_PARSE_JSON_INPUT`    | 无法解析 JSON 输入  |
| 422    | `FAILED_TO_PARSE_MARKDOWN_FILE` | 无法导出 Markdown |

## 支持与限制

REST API 使用与编辑器扩展相同的 Markdown 转换，因此支持的功能集完全一致。Markdown 导出会将 Tiptap 内容转换为兼容 CommonMark 的 Markdown。与 DOCX 不同，Markdown 没有富样式、页面布局或复杂表格格式的概念。

| **功能**        | **支持**                             |
| ------------- | ---------------------------------- |
| **文本内容**      | ✓ 段落、标题（1–6）、硬换行                   |
| **行内格式**      | ✓ 加粗、斜体、删除线、行内代码                   |
| **块元素**       | ✓ 引用块、代码块（带语言的围栏代码块）、水平分割线         |
| **列表**        | ✓ 无序列表、有序列表、任务列表、嵌套列表              |
| **表格**        | ✓ 基本的管道语法表格（单列表头行，不支持合并单元格）        |
| **链接**        | ✓ 带文本和 URL 的超链接                    |
| **图片**        | ✓ 带替代文本的图片引用（无尺寸）                  |
| **下划线**       | ✓ 自定义语法（`++text++`，非标准）            |
| **高亮**        | ✓ 自定义语法（`==text==`，非标准）            |
| **文本颜色 / 字体** | ✗ 没有颜色、字体族或字体大小的 Markdown 语法       |
| **文本对齐**      | ✗ 没有 Markdown 语法                   |
| **间距 / 缩进**   | ✗ 没有 Markdown 语法                   |
| **合并单元格**     | ✗ Markdown 表格不支持 colspan 或 rowspan |
| **页眉与页脚**     | ✗ Markdown 中没有这个概念                 |
| **页面布局**      | ✗ 没有分页、分节或页面大小                     |
| **数学公式**      | \~ 取决于扩展（如果配置了数学扩展，则使用 `$...$` 语法） |
| **脚注与尾注**     | ✗ CommonMark 不支持                   |

有关完整的 DOCX 功能对比，请查看[支持的功能](https://tiptap.zhcndoc.com/conversion/getting-started/feature-support-matrix.md)矩阵。