在线 HTML/Markdown 转换器：文档格式互转工具

什么是互转问题

HTML 与 Markdown 描述的是同一类「文档结构」，但表达能力不对等：HTML 能带 class、合并单元格、表单与任意嵌套；Markdown 刻意只保留可读语义。互转的价值是搬运结构，不是像素级复刻样式。

把片段粘进 HTML ↔ Markdown 互转，再视需要用 Markdown 预览 看渲染结果。

Markdown 示例

# 标题

## 二级标题

这是**粗体**和*斜体*文本。

- 列表项 1
- 列表项 2

[链接文本](https://example.com)

`行内代码`

HTML vs Markdown（选型直觉）

需要对照两版转换结果或配置时，用 文本 Diff；结构化数据请先走 JSON/YAML 工具，而不是指望 Markdown 保住对象语义。

为什么需要转换

1. 博客 / 静态站：Hugo、Jekyll、许多 CMS 以 Markdown 为源
2. GitHub README：从官网 HTML 摘结构进仓库
3. 邮件与论坛：Markdown 草稿 ↔ 需粘贴的 HTML 片段
4. 文档迁移：富文本导出 HTML 后收成可维护的 .md
5. API 文档：OpenAPI 描述字段里常见 Markdown

如何使用本站工具（以 UI 为准）

打开 HTML/Markdown 转换器：

1. 左侧编辑 HTML，右侧编辑 Markdown（两侧都是源码编辑器，不是自动探测单一输入框）
2. 点 转 Markdown：HTML → Markdown（Turndown）
3. 点 转 HTML：Markdown → HTML（marked）
4. Markdown 侧有内容时可复制 / 清空；错误信息显示在工作区下方

不会在粘贴时自动识别格式并转换——必须点对应按钮。旧文若写「自动检测格式」，以当前 UI 为准。

实现注记：Turndown 与 marked

对应 src/tools/HtmlMarkdownTool.tsx：

HTML → Markdown（Turndown + GFM）

逻辑在 src/utils/tools/html-markdown.ts：

const turndownService = new TurndownService({
  headingStyle: 'atx',
  codeBlockStyle: 'fenced',
});
turndownService.use(gfm); // turndown-plugin-gfm：表格 / 删除线 / 任务列表等

• 已启用 GFM 插件：常见 HTML <table> 会转成管道表格 |...|
• <del> 删除线、任务列表复选框等也会按 GFM 规则处理
• 合并单元格、复杂 colspan/rowspan、带样式的布局仍会丢失或降级——需要完整表格语义时改用 Markdown 表格生成器

Markdown → HTML（marked）

• 调用 marked.parse(markdown)；当前 marked 默认 gfm: true
• MD→HTML 支持 GFM 表格、任务列表、删除线等
• 输出是字符串，写入 HTML 编辑器；本页不会把该字符串当成预览 DOM 执行
• breaks 默认为 false：单个换行通常不会变成 <br>

往返 HTML → MD → HTML

简单管道表可往返；得到的仍是「语义近似、样式归零」：class/id、复杂布局、合并单元格、表单控件会丢或变形。

验证习惯：转换后把 Markdown 贴进 预览工具（react-markdown + remark-gfm），确认你关心的结构还在——尤其是表格。

CommonMark / GFM 如何改变答案

「哪种 Markdown」决定转换与验收标准：

方言不匹配时，先确认目标渲染器是否启用 GFM，再决定是否用手写/生成器补齐。

安全边界

1. 互转工具把 HTML 当文本编辑，不是消毒后的安全预览沙箱
2. marked 产出的 HTML 字符串可能含标签；若你复制到生产页并用 innerHTML / 未消毒模板挂载，需自建白名单或消毒
3. 预览用户可见渲染时，优先用 Markdown 预览 的 React 路径（见预览指南的 XSS 说明）
4. 要把用户文本放进 HTML 属性或混排场景，先看 HTML 实体编码 与实体编码指南

代码中的同类栈

JavaScript（与本站同族）

const TurndownService = require('turndown');
const { gfm } = require('turndown-plugin-gfm');
const { marked } = require('marked');

const turndown = new TurndownService({
  headingStyle: 'atx',
  codeBlockStyle: 'fenced',
});
turndown.use(gfm);
const markdown = turndown.turndown('<h1>标题</h1><p>内容</p>');
const html = marked.parse('**粗体** 和 *斜体*');

生产环境请按需消毒 HTML，不要假设默认配置等于本站 UI。

Python（示意）

import markdown
import html2text

html = markdown.markdown('# 标题\n\n**粗体**内容', extensions=['tables'])
h = html2text.HTML2Text()
h.ignore_links = False
markdown_text = h.handle('<h1>标题</h1><p>内容</p>')

看起来像「转换器坏了」的坑

实体与智能引号

CMS 导出的 HTML 常带  、弯引号或 &。Turndown 有时输出字符、有时保留实体，取决于 DOM 路径。若 Markdown 之后再经一层 HTML 转义，会出现 & 双重编码。用 文本 Diff 对照可信片段；需要实体形态时用 HTML 实体编码。

图片与相对路径

<img src="/media/a.png"> 转成 Markdown 后仍指向 /media/a.png——相对原站正确，相对 git 仓库根往往错误。转换不会下载二进制，路径改写仍是你的工作。

「MD→HTML 无损」指结构，不指 CSS

CommonMark/GFM 构造都能映射到某种 HTML，但 class、内联样式、布局包装在 Markdown 往返后回不来。不要把本工具当成保样式的美化打印器。

预览 vs 互转不一致

Markdown 预览 用 react-markdown + remark-gfm；互转的 MD→HTML 用 marked。两者都偏 GFM，但属性顺序、列表紧/松包裹、自动链接边缘案可能不同。不一致时以目标站实际栈为准，不要假定「本站预览 ≡ marked 字符串 ≡ GitHub」。

三十秒验收清单

1. 用含标题、列表、链接、围栏代码（以及你关心的表格）的样例各转一次
2. 把 Markdown 贴进预览，确认结构
3. 若 HTML→MD 后表格消失，用 表格生成器 重建
4. 合并前与上一版文档做 Diff

批量管线原则（目录级）

1. 幂等：重复跑不应双重转义实体或重复包一层围栏
2. 先抽样 Diff：转换到旁路目录，用 文本 Diff 肉眼抽 10 个文件
3. 失败隔离：单文件失败进隔离区，不要整批中止后静默丢文件
4. HTML 只读留底：几个月后发现转换缺陷时，从源 HTML 重跑比改「已损坏的 Markdown」便宜

配置类内容若其实是 YAML/JSON，应走 YAML ↔ JSON / JSON 格式化，而不是 HTML↔Markdown。

FAQ

Markdown 有唯一标准吗？

没有单一「全世界同一行为」的标准。CommonMark 约束核心；GFM 是开发者文档事实超集；各 Wiki 还有私货。互转前先固定目标方言。

标准 Markdown 支持表格吗？

严格 CommonMark 核心不包含管道表格；GFM 支持。本站 MD→HTML（marked）与 HTML→MD（Turndown + GFM 插件）均可处理常见管道表；合并单元格等复杂表仍可能降级。

样式会丢吗？

会。CSS、浮动、定位、大多数 class 不会变成 Markdown。留下的是标题层级、列表、链接、强调等结构信号。

和预览工具怎么分工？

延伸阅读

• Markdown 预览指南 — remark-gfm、安全渲染、踩坑
• Markdown 表格生成器指南 — 管道表语法与生成行为
• YAML ↔ JSON 指南 — 配置不要硬塞进 HTML 互转
• JSON 格式化指南 — 示例 JSON 进文档前的整理
• 文本 Diff 指南 — 转换前后抽样对照
• HTML 实体编码指南 — 嵌入 HTML 时的转义

本文出自 ToolVault 工具匣。首页 汇集了更多浏览器本地工具。