HTML 转 Markdown 指南：保留结构、链接、表格与图片

哪些结构能保留，哪些会丢失

转换前先确定“只要正文”还是“保留导航与脚注”。整页 HTML 常包含菜单、Cookie 提示和推荐卡片；把这些一起转进去会污染文章。最可靠的输入是内容区域的 HTML 片段，而不是整个网站源码。

WebUtils 工具页操作步骤

1. 打开 HTML 转 Markdown 转换器，确认左侧是 HTML 输入区、右侧是 Markdown 输出区。
2. 从浏览器开发者工具或 CMS 导出内容区域，复制真实 HTML。不要把页面中的密码、令牌、用户资料一起粘贴。
3. 选择标题风格：仓库普遍使用 # 时选 ATX；旧文档明确要求下划线标题时才选 Setext。
4. 选择无序列表符号，保持与现有仓库的 lint 规则一致。不同符号混用会制造无意义的 diff。
5. 点击“开始转换”，先观察标题、列表、链接、图片和代码块，再复制结果。
6. 用 Markdown 预览器渲染输出，重点检查嵌套列表、表格对齐和链接是否可点击。
7. 把相对 URL 转成仓库或站点实际路径；确认图片有替代文本，代码块补上语言标识。
8. 删除导航、广告、隐藏文本和重复标题，最后用 HTML/Markdown 格式化工具整理换行。

工具使用浏览器中的 Turndown 逻辑转换常见节点，适合中小型片段。它不会抓取远程网页、下载图片或替你判断文章主内容；输入必须由你提供，输出仍需要审阅。

前后对照：一个内容卡片如何变化

输入 HTML：

<article>
  <h2>部署步骤</h2>
  <p>先安装 <strong>Node.js 20</strong>，再运行 <code>npm install</code>。</p>
  <ul><li>准备环境</li><li>运行测试</li></ul>
  <p><a href="/docs/start">查看完整文档</a></p>
</article>

输出 Markdown 可能是：

## 部署步骤

先安装 **Node.js 20**，再运行 `npm install`。

- 准备环境
- 运行测试

[查看完整文档](/docs/start)

这里结构和强调被保留，article 容器本身被省略。若目标仓库部署在子路径，/docs/start 可能需要改成相对路径或完整 URL；转换器不会知道你的发布基路径。

表格、链接和图片的人工复核

表格。 简单的矩形表格可以转成 Markdown；rowspan、colspan、多行表头和单元格内 HTML 常会被展平。合并单元格的语义不能靠对齐空格恢复，应改成列表、分节表格或保留原 HTML。

链接。 文字为空的链接、JavaScript 链接、下载链接和带追踪参数的链接需要单独处理。把 javascript:void(0) 直接写进 Markdown 不但无用，还可能制造安全问题。内部链接迁移后要检查大小写、末尾斜杠和锚点。

图片。 src 可能只是占位图，真实地址藏在 data-src；转换器只能看到输入中的属性。图片尺寸、懒加载、鉴权 CDN 和相对路径都需要人工修复，替代文本也不能用文件名敷衍。

代码与特殊字符

HTML 中的 <、& 等实体会被还原为可读字符，但在代码示例中应保留字面含义。比如 <button> 出现在代码块内时，Markdown 输出必须继续位于围栏中，不能被当作 HTML 标签。

<button type="submit">保存</button>

如果原文是 <pre><code class="language-js">...</code></pre>，语言类名通常可以帮助你手工补上 `js 。转换器不一定能识别所有类名，也不会验证代码是否可运行。迁移后应让对应语言的格式化器或测试工具接手。

错误表：转换成功不等于内容正确

每次转换后至少抽查一个标题、一个嵌套列表、一个链接、一个图片和一个代码块。只看输出长度无法发现结构性丢失。

真实场景：文档迁移的四条路线

CMS 迁移到 Git。 从文章正文容器复制 HTML，转换成 ATX 标题后提交到仓库。迁移脚本统一内部链接和图片目录，再让 Markdown 预览器逐篇检查，避免把 CMS 的推荐模块也提交。

知识库归档。 旧系统导出带表格和脚注的 HTML。先转换主文，脚注改成“参考资料”列表；复杂合并表格保留一小段 HTML，保证信息不被错误展平。

API 文档重写。 HTML 示例常含 <code> 和 <pre>。转换后给代码块补语言标识，再在 CI 中运行格式化器，确保复制出来的命令不会因实体解码而变化。

网页研究笔记。 只保留选中的内容片段，并记录原页面 URL 和抓取日期。转换结果用于个人笔记，不应把受版权限制的整页内容重新发布。

安全、版权与隐私边界

• 浏览器本地转换减少了上传路径，但剪贴板、下载文件和屏幕共享仍可能泄露内部文档。
• 转换器不会主动执行输入脚本；输出放入网站前仍要按发布系统做 HTML 清洗，不能把 Markdown 当作天然安全。
• 删除 javascript: 链接、内联事件和可疑 iframe；Markdown 中的 URL 仍可能指向钓鱼站点。
• 只处理你有权复制和再发布的内容。网页转 Markdown 不会自动消除版权、个人信息或访问控制义务。
• 图片和附件可能需要登录才能访问。迁移前确认许可证、存储位置和失效策略。

相关工具怎么选

转换后如何维护版本

迁移到 Git 后，建议把原始 HTML 片段和生成的 Markdown 关联起来，至少记录来源 URL、导出日期、转换选项和人工修改点。这样后续原站更新时可以重新转换并比较差异，而不是把整篇文章覆盖。标题风格、列表符号和换行规则应写进仓库贡献指南，避免每个人用不同选项生成大面积无意义的格式变化。若文章包含图片，最好同时登记资源路径和许可证，链接失效时能定位责任。

什么时候保留原 HTML

有些内容不应强行降级。例如交互式代码演示、带合并单元格的统计表、需要无障碍 ARIA 属性的组件，转成 Markdown 后可能失去操作语义。可以只把说明文字转成 Markdown，在需要精确结构的局部保留经过清洗的 HTML，并为读者提供纯文本替代。混用要有明确理由和安全审查，不能为了追求“全是 Markdown”而牺牲信息完整性。

常见问题