如何转换为markdown格式？

html2text最稳，禁用折行（-b 0）、启用Unicode和GitHub模式可批量转；pandoc保真但表格敏感，需列数一致；turndown已停更，Node.js推荐cheerio+remark-html；在线工具不可控，转换本质是降维取舍。

直接用 html2text 命令行最稳，不依赖浏览器、能批量、参数可控；pandoc 保真度高但对表格结构敏感；turndown 适合前端或 Node.js 环境定制，但已停止维护，别用它处理复杂 HTML。

用 html2text 批量转，绕过换行和宽度干扰

html2text 默认会按 79 字符自动折行，导致段落被切碎、列表缩进错乱、代码块变形。关键是要关掉这个行为：

• 加 -b 0 参数禁用 body width 限制（-b 是 body_width 的缩写）
• 加 --unicode-snob 正确处理中文引号、破折号等 Unicode 符号
• 加 -g 启用 GitHub 兼容模式，让表格生成标准 Markdown 表格语法
• 批量转换命令示例：for f in *.html; do html2text -b 0 --unicode-snob -g "$f" > "${f%.html}.md"; done

注意：html2text 不解析 JavaScript、不执行 DOM 渲染，只做纯文本解析——所以它转不了动态插入的内容，这点和浏览器环境工具有本质区别。

pandoc 转表格时列数不一致？先检查和

pandoc -f html -t markdown 遇到表格容易丢行或少列，根本原因是它把 <thead> 和 <tbody> 当作独立结构校验列数。常见错误现象：Warning: Ignoring invalid table row。

立即学习“前端免费学习笔记（深入）”；

• 确保每行 <tr> 内的 <th>/<td> 数量一致，尤其注意 colspan 和 rowspan 属性——它们必须提前展开或删除
• 避免使用 style="display:none" 隐藏的单元格，pandoc 会照常解析，导致列数错位
• 临时救急：加 --wrap=none 防止换行干扰列识别；更可靠的做法是先用 html2text -b 0 提取结构化文本，再人工补分隔行

Node.js 里用 remark-html，不是 turndown

turndown 已归档、不再维护，且对自定义标签（如 <figure>、<details>）支持弱；当前推荐组合是 cheerio + remark-html：

• cheerio 加载 HTML 后可精准过滤广告 <div class="ad">、保留特定 class、展开 <figure><img></figure> 为带 alt 的 Markdown 图片
• 清理后的 HTML 字符串交给 remark-html（不是 rehype-html），它能正确处理嵌套强调、列表缩进、空行逻辑
• 别在浏览器里跑 cheerio——它不兼容 DOM 环境，只适用于 Node.js
• 性能上单文件约 20–50ms，100 个文件无压力，但不适合前端实时转换

在线工具和浏览器插件为什么总出错

像 “Markdown Preview Enhanced” 或 cloudconvert.com 这类方案，本质是调后端服务或走简化版解析逻辑，不可控点太多：

• <blockquote> 可能被转成普通段落，<code class="js"> 的语言标识直接消失
• 无法注入 frontmatter、不支持目录映射、不能批量重命名输出文件
• 遇到 <script> 或内联 style 时，多数工具静默跳过，不报错也不提示
• 所有这类方案都绕不开一个事实：HTML 到 Markdown 不是“翻译”，而是“降维”——表格跨行、CSS 布局、JS 动态内容，全得人工判断取舍

真正难的从来不是怎么转，而是转完之后要不要删 colspan、要不要补空单元格、要不要把 <h2 class="section-title"> 里的 class 当语义保留——这些决策没法自动化。