---
title: "HTML 转 Markdown"
description: "HTML 转 Markdown 是一款把上传的 .html 文件变成用于提示词的结构化 Markdown 的转换器。公开试用接受最大 10 MB 的文件。"
url: https://markitdown.ai/html-to-markdown
updated: 2026-09-26
source: markitdown.ai
---
# HTML 转 Markdown
> HTML 转 Markdown 是一款把上传的 .html 文件变成用于提示词的结构化 Markdown 的转换器。公开试用接受最大 10 MB 的文件。
## 如何把 HTML 转 Markdown
- 在 HTML 转 Markdown 转换器里上传一份受支持的源文件。选一个你能与结果对照的文件，并在开始前查看匿名试用限额。
- 把 HTML 转 Markdown 的输出与来源对照。在把任何内容复制进别的工具前，检查标题、表格单元格和最后一段。
- 复制复核过的 HTML 转 Markdown 输出，用于你的下一项任务。若需要账号内的持续转换、保存历史、批量或 API 访问，请选择 Lite、Pro 或 Max 订阅。
## 为什么使用 HTML 转 Markdown
- 语义化标题 — 把有意义的 HTML 标题结构转成 Markdown 大纲，并在源码视图里复核得到的层级。
- 链接与列表 — 把受支持的链接文字和列表结构带进 Markdown，再在你复用输出的上下文里核对目标。
- 保存的快照输入 — 处理你已经拥有的 HTML，而不去抓取一个自原始导出以来可能已变动的在线页面。
- 代码与表格复核 — 在目标渲染器里检查围栏代码和简单表格，然后再发布从 HTML 迁移来的文档。
- CSS 不进入文本 — 聚焦文档内容，而不是复现定位、动画或某个交互式网站主题。
- 从 HTML 自动化 — 对受支持的文件或行内文本输入使用 HTML API 路径，并在集成里处理异步完成。
## 为什么 HTML 文件仍带着外壳
- 样板噪声 — 当保存的文件包含整页时，导航、页脚和广告会围住你真正想要的内容。
- 嵌套标记 — 深层嵌套的标签和行内样式会遮蔽真实的文档结构。
- 标题不一致 — HTML 里的标题层级常被误用；干净的 Markdown 会在标签存在处规范化层级。
## 这款 HTML 转换器保留什么
- 上传文件，不抓取 — 这个工具转换上传的 .html 或 .htm 文件。要按 URL 转换在线网页，请用 /url-to-markdown 的 URL 转 Markdown 转换器。
- 标题与表格 — HTML 标题标签（h1–h6）映射为 Markdown 标题，表格元素变成 Markdown 管道表格。
- 行内脚本与样式 — 行内 script 和 style 块会从输出里移除；只保留可见的文档内容。
- 保存文件里的样板内容 — 当前转换器保留页面文本，其中可能包含随文件一起保存的导航、页脚和其它样板内容。使用前请复核 Markdown。
## HTML 转 Markdown 的真实工作流
- CMS 导出 — 为 Markdown 目标环境准备导出的文章，检查链接、媒体引用和标题结构。
- 文档迁移 — 在迁移一批 HTML 指南前，先在新渲染器里复核代码示例和表格。
- 归档快照 — 处理已知的已保存页面，而不是依赖某个在线 URL 今天恰好返回什么。
- 文本摄取 — 转换你自己授权的工作流所收集的 HTML，并在建立索引前复核周边的导航。
## HTML 转 Markdown API
用 POST /v1/convert/html，带上 x-api-key 请求头和受支持的源文件。已完成的请求可以内联返回输出；HTTP 202 表示转换仍在进行。读取 Location 响应头并在访问文件输出前轮询它。一次 multipart 请求最多接受 100 个文件；订阅额度和总请求限额同样适用。把 API 密钥放在你的服务器环境里。API 访问需要 Lite、Pro 或 Max 订阅。
```bash
curl -i "https://api.markitdown.ai/v1/convert/html" \
-H "x-api-key: $MARKITDOWN_API_KEY" \
-F "file=@source.html"
# If HTTP 202, GET the Location URL with the same API key.
```
## HTML 文件与 URL 的区别
HTML 转 Markdown 从你已经拥有的 HTML 开始。URL 转 Markdown 从一个网络地址开始，先抓取公开页面再转换。当你需要处理一个已知的快照、一份模板导出或你自己的系统已收集的内容时，用保存好的 HTML 文件。当公开页面就是你现在想检索的来源时，用 URL 工具。HTML 转换器不执行脚本去填补缺失的内容，所以一个保存下来的应用外壳可能只包含你在浏览器里看到的文章的一小部分。在排查 Markdown 输出之前，先检查你提交的来源，确认你需要的文本确实存在。
## 检查输出结果
HTML 转 Markdown 可以把标题、段落、列表、链接、代码和简单的表格表示为紧凑的文本形式。CSS 定位和交互控件在普通 Markdown 里没有直接对应物。与用带样式的通用容器拼成的页面相比，一个有意义地使用标题元素的页面，会给转换器更清晰的大纲。在 Markdown 源码里复核导出的标题层级和一段有代表性的嵌套列表。对表格，确认表头仍然描述它下面的值。目标是可读地呈现文档内容，而不是重建浏览器的版式、悬停行为或视觉主题。
## 导航与链接
HTML 转 Markdown 可能把导航、页脚文本和其它内容与正文一起保留下来。不要假设转换器已识别出正文，或已移除每一条广告。在把导出内容加入检索索引前，检查开头和结尾有没有重复的菜单。一份保存下来的 HTML 文件还可能包含相对链接，其含义取决于原站的位置。在你发布 Markdown 的上下文里核对这些目标，并在自己的工作流里提供有意义的来源引用。转换链接语法并不证明目标仍然存在，而本地文件也不会自动提供原网站的基址。
## CMS 迁移
在导出整个 CMS 之前，先用一篇有代表性的文章测试 HTML 转 Markdown。选择一篇包含表格、代码、图片、链接和嵌套标题的文章，这样你就能早发现重要差异。在目标渲染器里对照结果，因为不同的 Markdown 引擎对扩展的支持可能不同。把原始 HTML 导出留作审计副本，并记录它属于哪篇文章。在迁移流程里决定如何处理重复的导航和媒体资源；这个转换器不会替你发布内容或搬移网站的文件。一份经过复核的 Markdown 导出是这次迁移的便携起点，而不是已完成的站点迁移。
## 文件保留了哪些内容
这个工具转换你已经拥有的文件。它不抓取网络。文件里的导航、页脚和其它样板内容仍可能出现在 Markdown 里——嵌入前请先复核。要按 URL 转换在线网页，请用 URL 转 Markdown 转换器。
- HTML 标题标签（h1–h6）映射为 Markdown 标题。
- HTML 表格变成 Markdown 管道表格。
- 行内 script 和 style 块会被移除；只保留可见的文档内容。
## 示例：markitdown.ai API 文档的 Quickstart 页
Source: https://markitdown.ai/docs/quickstart
```markdown
[Home](/)
Getting started
[Introduction](/docs)[Authentication](/docs/authentication)[Quickstart](/docs/quickstart)
Core
[Convert](/docs/convert)[Conversions](/docs/conversions)[Batches](/docs/batches)[Conversion Files](/docs/files)[Markdown Render](/docs/render)
Developer
[API keys](/docs/api-keys)[Webhooks](/docs/webhooks)
Reference
[URL fetcher](/docs/fetcher)[Errors & limits](/docs/errors-and-limits)
API reference
[All endpoints](/docs/api)[Error codes](/docs/errors)
Quickstart
Getting started
# Quickstart
Convert your first document to Markdown with the v1 API: one POST /v1/convert call, then read or poll the result.
```
## FAQ
### HTML 转 Markdown 是怎么工作的？
HTML 转 Markdown 把受支持的来源转换成可读的 Markdown，便于复核和复用。匿名试用接受每个文件最大 10 MB、25 页，每个 IP 每小时 3 次转换、每天 10 次。使用前请把结果与来源对照。
### HTML 文件最大能有多大？
公开转换器接受最大 10 MB 的 HTML 文件。
### 保存的页面会移除导航和样板内容吗？
当前转换器保留页面文本，其中可能包含导航、页脚和其它样板内容。使用前请复核 Markdown。
### HTML 标题如何处理？
HTML 标题标签（h1–h6）直接映射为 Markdown 标题层级，保留文档层级。
### HTML 表格会保留吗？
会。HTML 表格会转换成 Markdown 管道表格，并保持列结构完整。
### 行内脚本和样式呢？
行内 script 和 style 内容会被移除。只输出可见的文档文本和结构。
### 预览 HTML 需要注册吗？
不需要。匿名试用让你预览并复制结果。账号内转换和保存历史需要 Lite、Pro 或 Max 订阅。
### 可以从 API 转换 HTML 吗？
可以。把 .html 文件 POST 到 /v1/convert/html，若没有内联完成就轮询这次转换。见 /developers。
## Related
- [Markdown converter for documents and web pages.](https://markitdown.ai/)