首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API「HTML 与 Markdown 互转」接口功能介绍

数据鱼API「HTML 与 Markdown 互转」接口功能介绍

原创
作者头像
用户12862874
发布于 2026-11-21 21:32:57
发布于 2026-11-21 21:32:57
60
举报

接口简介

「HTML 与 Markdown 互转」是数据鱼API平台提供的双向格式转换接口,Base 路径 /api/htmlmd,共 3 个端点:ping 探活,toMarkdown 把 HTML 转成 Markdown,toHtml 把 Markdown 转成 HTML。它适合内容迁移、CMS 导入导出、把富文本正文降级为纯文本标记,以及给文档站点做格式统一。

两个方向的实现并不同源。toMarkdown 用 DOMDocument 遍历节点树,支持标题、段落、加粗斜体、行内代码、带语言标注的代码块、链接与图片、有序无序及嵌套列表、引用、表格和常见容器标签,script 与 style 的内容直接丢弃而不是转义输出。toHtml 走的是 Markdown 子集解析,覆盖标题、强调、行内代码、带语言 class 的围栏代码块、链接图片、列表、引用、分隔线与段落,不包含表格语法。

安全边界在文档里写得很明确:toHtml 默认转义输入中的原始 HTML,只有显式传 allow_html=1 才保留;toMarkdown 不执行任何脚本与样式;XML 解析启用 LIBXML_NONET,不发起外部实体请求。整个服务基于 PHP 的 ext-dom,不依赖数据库、缓存或外部 HTTP 服务,输入上限 512 KB。

三个端点都要求鉴权,ping 也不例外,只有跨域预检的 OPTIONS 请求免校验。

端点总览

方法

路径

说明

鉴权

GET

/api/htmlmd/ping

健康检查,返回版本号与服务器时间

是

POST

/api/htmlmd/toMarkdown

HTML 转 Markdown

是

POST

/api/htmlmd/toHtml

Markdown 转 HTML

是

通用约定

  • 鉴权:通过 X-API-Key 请求头或 ?api_key= 查询参数传递全站统一 Key;缺失返回 4011,无效返回 4013,HTTP 状态 401。
  • 请求格式:两个转换端点使用 POST 提交 JSON,字段名固定为 html 与 markdown;响应统一为 {"code": 0, "msg": "success", "data": {...}}。
  • 输入上限:单次文本最长 512 KB,超出或 HTML 解析失败都返回 4002,HTTP 400,msg 说明具体原因。
  • 错误码:缺少参数 4001,参数非法 4002,鉴权 4011/4013,路由不存在 4040,内部异常 5000;本服务不依赖上游,正常调用不会出现 5031/5032。以上与数据鱼API平台的统一约定一致。
  • 幂等性:转换是纯函数,同一输入重复调用输出一致,不做缓存也不落盘。

核心端点详解

HTML 转 Markdown

把一段 HTML 片段转为 Markdown 文本,适合把历史富文本正文转成可版本管理的标记文件。

参数

类型

必填

默认

说明

html

string

是

无

待转换的 HTML 文本,最长 512 KB

返回只有一个字段 markdown,即转换结果。输出保留段落之间的空行,列表项以 - 开头,标题按层级输出 #,加粗与斜体转为 ** 与 *,行内代码用反引号包裹,代码块按 pre/code 的语言 class 写出围栏标注。

代码语言:javascript
复制
{"html": "<h2>标题</h2><p>这是 <strong>加粗</strong>,还有<a href=\"#section\">链接</a>。</p><ul><li>项目一</li></ul>"}

转换为 ## 标题、段落一行与一个列表项。script 与 style 标签连同内部文本一起被丢弃,不会被转成可见内容,也不会以 HTML 形式残留在输出里。

Markdown 转 HTML

把 Markdown 文本渲染为 HTML 片段,用于生成邮件正文、静态页面或富文本编辑器初值。

参数

类型

必填

默认

说明

markdown

string

是

无

待转换的 Markdown 文本,最长 512 KB

allow_html

string

否

空

传 1 时保留输入中的原始 HTML;缺省或不传则转义

返回只有一个字段 html。标题输出为 h1 至 h6,强调输出 strong 与 em,围栏代码块输出 pre/code 并附带 language-xxx 类名,列表输出 ul/li,引用输出 blockquote。原始 HTML 默认被实体转义,因此输入里的脚本标签会以文本形式显示;确实需要内嵌 HTML 时再传 allow_html=1,此时应自行保证输入可信。

代码语言:javascript
复制
{"markdown": "# 标题\n\n- 项目一\n- **加粗**\n\n```php\necho 1;\n```", "allow_html": "1"}

健康检查 ping

参数

类型

必填

默认

说明

无

—

—

—

该端点不接受业务参数

代码语言:javascript
复制
GET /api/htmlmd/ping

返回 code=0、msg=pong,data.version 为接口版本(当前 1.0),data.time 为服务器本地时间,格式 YYYY-MM-DD HH:MM:SS。该端点同样校验 Key,探活请求也必须带上鉴权。

数据与限制

  • 端点规模:3 个;无分页、无批量、无异步任务,转换在请求内同步完成。
  • 输入上限:512 KB,超限直接拒绝,不做截断;超大文档应在调用方按章节切分后分批转换。
  • 能力差异:HTML 侧支持表格与嵌套列表,Markdown 侧不解析表格语法,表格内容会退化为普通段落;需要保表格时优先走 HTML 方向。
  • 内容处理:toMarkdown 丢弃 script 与 style 内容;toHtml 默认转义原始 HTML,allow_html=1 才保留。
  • 无状态:不保存请求内容,不返回任务 ID,转换结果需调用方自行持久化。
  • 编码:输入输出均为 UTF-8 字符串,msg 为英文短语,不含多语言文案。

典型使用场景

  • 把旧 CMS 导出的 HTML 正文批量转成 Markdown,提交到 Git 仓库做版本管理。
  • 文档站把 Markdown 源文件渲染成 HTML 片段,嵌入页面模板。
  • 邮件系统把 Markdown 模板转成 HTML 正文,并对用户输入默认保持转义。
  • 语料清洗时把网页正文降级为 Markdown,去掉脚本与样式后再进入检索或训练流程。

注意事项

  • allow_html 是字符串而不是布尔值,传 "1" 生效,传 true 或 "true" 的行为文档未定义;开启后原始 HTML 原样保留,必须自行做可信来源校验。
  • 两个方向能力不对等:Markdown 侧没有表格与嵌套列表的完整支持,往返转换可能出现结构损失,不要把 htmlmd 当作无损格式转换器。
  • 512 KB 是硬上限,超限返回 4002 而不是截断后成功;批量任务应先估算字节数,避免整篇被拒。
  • 解析失败与超限共用 4002,仅凭错误码无法区分原因,需要读取 msg。
  • 输出是片段而非完整文档:toHtml 不会补 html、head、body 等骨架标签,直接当整页返回会缺少文档结构。
  • 以上参数与行为以数据鱼API当前实现为准。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • HTML 转 Markdown
    • Markdown 转 HTML
    • 健康检查 ping
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档