Markdown 转 HTML：干净的发布工作流 | Toolars

发布管线需要一种能熬过工具、托管平台和重新设计的主格式。纯文本 Markdown 就是这个主版本：任何编辑器都能读，版本控制里差异清晰，与今年用来渲染它的 HTML 模板无关。

可移植可移植：Markdown 文件在任何编辑器中都能打开，无需迁移工程即可转换为 HTML、PDF、幻灯片或文档系统。
可对比可审阅：文字改动呈现为干净的行级差异；而 HTML 主版本会把一个词的修改埋在标签和属性里。
结构而非样式关注点分离：源文件只承载结构——标题、列表、引用——排版交给主题决定，重新设计永远不会触碰存档。

有意为之的转换器只支持一个子集，因为每多支持一种构造，就多一条夹带未经审阅标记的通道。在依赖转换之前，先弄清你的内容相对这条线的位置。

干净转换干净转换：最多六级标题、段落、粗体、斜体、删除线、行内代码、围栏代码块、有序与无序列表、块引用、分隔线和行内链接。
已知损失被压平或丢弃：嵌入图片、表格、脚注、任务列表和原始 HTML 块在子集中没有对应表示，因此会消失或退化为纯文本。
用真实文章测试测试方法很简单：转换一篇有代表性的文章并阅读输出。结果里缺的东西，从来都不在契约里。

转换出的 HTML 注定要被注入页面，而被注入的标记就是攻击面。干净的管线默认清洗：脚本、样式、iframe、表单、嵌入和图片一律移除，未知标签解包为文字，属性全部剥除。

移除主动内容携带主动行为的元素——script、style、iframe、object、embed、svg、form、video、audio、img——连同内容一起移除，而不只是被中和。
剥除属性属性整体消失：没有行内样式、没有事件处理器、没有从源里夹带的类名。锚点只在通过协议检查时保留 href。
报告而非静默工作区会报告移除了什么——被丢弃节点与被剥属性的计数——清洗是可见事件，而不是静默改动。

渲染出的文档大部分是链接，而链接正是清洗最讲究的地方。转换器只接受 http、https 和 mailto 地址以及页内 #片段；其余——javascript:、data:、协议相对的把戏——都会失去 href，渲染为纯文本。

协议白名单存活的链接会被盖上 rel="noreferrer noopener"，被点开的链接无法看到或操控打开它的页面。
noopener noreferrer同一规则双向适用：Markdown 里写的链接在转换时检查，粘贴的 HTML 里的 href 在清洗后重新检查。
标签文字保留当链接失去协议时，标签文字仍在——坏掉的导航立即可见，而不是把一个静默的 javascript: 载荷带进发布。

把 HTML 转回 Markdown 是抢救，不是往返。子集理解的结构——标题、段落、强调、列表、引用、代码——能完好回来；其余的在转换开始之前就被清洗器丢弃了。

表格塌缩表格塌缩：子集没有表格语法，一格一格的网格会变成一串单元格文字，表格数据需要重写或改用 CSV 导出。
媒体被移除图片、视频和交互嵌入按设计消失——在生成 Markdown 之前，清洗器已把它们作为主动内容移除。
文字比样式长寿子集之外的格式——span、div、类名、锚点目标——不留痕迹；文字幸存，样式不幸存。

转换在发布时运行，每篇文章一次：用 Markdown 起草和审阅，转换成清洗过的 HTML，核验渲染结果，然后发布。一切都在浏览器标签页里发生——草稿从不上传，这在内容属于未公开的发布时尤其重要。

发布时执行工作区接受最大 256 KiB 的源文本，产出最大 512 KiB 的输出——足够一本书的章节规模——超过限制时会报出明确的错误，而不是静默截断。
明确的上限把输出复制进 CMS 字段，或下载为文件；两条路径拿到的都是预览中那份清洗过的文档。
重新转换，别打补丁把 Markdown 和它记录的代码一起放进版本控制，每次修改后重新转换，而不是修补旧 HTML。