Markdown 转 HTML 完全指南：公众号 / 邮件 / 网站三种用法

场景 1：微信公众号。公众号编辑器阉割了大量 CSS，只接受部分标签和 style 属性，无外部样式表、无 @font-face、无 JavaScript。要让排版在公众号里不崩坏，必须把所有样式以 inline style 的方式嵌入到 HTML 标签内。

场景 2：HTML 邮件。邮件客户端（Outlook、Gmail、Apple Mail）对 CSS 的支持参差不齐，很多样式属性在某些客户端被无视或破坏。安全的做法是用 table 布局（如 1990 年代的网站），避免 float、flex、grid，所有样式都 inline。

场景 3：网站 CMS。网站通常有统一的 CSS 框架（Tailwind、Bootstrap），Markdown 生成的 HTML 需要兼容这些框架的 class，还要考虑 SEO（heading 层级、alt 文本、结构化数据）。

三个场景，三套规则。同一个 Markdown 源文件，直接转换无法同时满足全部需求。

标准 Markdown 只支持基础的标题、列表、代码块。GitHub Flavored Markdown（GFM）在此基础上添加了表格、删除线、任务列表、代码行高亮。但问题是：公众号、邮件、甚至一些旧网站的 Markdown 转换器不支持 GFM。选择转换工具时务必检查是否启用了 GFM 模式。常见转换库如 marked.js、markdown-it 都默认支持 GFM，但部分 WordPress 插件可能需要手动启用。

微信公众号编辑器会自动过滤掉你写的 <style> 标签，因此所有样式必须内联（inline）。假设你的 Markdown 原文有代码块需要高亮，标准的 HTML 输出可能是 <pre><code class="language-python">...</code></pre>。公众号收到后，class 被忽略，代码无背景色。解决方案是生成时直接嵌入背景色和字体：<pre style="background: #f5f5f5; padding: 12px; border-radius: 4px;"><code style="color: #333;">...</code></pre>。同理，所有链接、加粗、斜体、列表都需要手动补充 style 属性。推荐使用专门的「Markdown 转微信公众号 HTML」工具或在转换后用正则 / DOM 操作批量补样式。

主流的 HTML 邮件采用表格布局，因为几乎所有邮件客户端都支持 table。Markdown 转换器输出的 div 和 CSS 在 Outlook 中常常崩坏。标准 Markdown 生成的 HTML 可能是 <div style="margin: 20px; padding: 10px; border: 1px solid #ccc;"><p>内容</p></div>，但 Outlook 可能无法正确渲染 margin。改成表格则更安全：<table cellpadding="0" cellspacing="0" border="0" width="100%"><tr><td style="padding: 10px; border: 1px solid #ccc;">内容</td></tr></table>。邮件 HTML 的其他禁忌：不用 background-image、避免媒体查询、@font-face 大多被禁用、JavaScript 必然被过滤。保险的做法是用专门的邮件模板框架如 MJML 或 Stripo，而不是直接从 Markdown 转换。

在自己的网站嵌入 Markdown 转换的 HTML 时，最大的考虑是 SEO 和视觉一致性。SEO 方面需确保 heading 标签正确（<h1> 用一次，后续用 <h2>、<h3>），图片有 alt 属性，链接有描述性文本。视觉方面，Markdown 转换后的 HTML 应该自动添加与网站框架兼容的 class。比如用 Tailwind 的网站，应输出 <h2 class="text-2xl font-bold my-4">标题</h2> 而非裸 HTML。推荐手动转换或用 rehype 插件（如 rehype-react）在转换时注入 class，避免样式混乱。

Markdown 编辑器（Typora、Obsidian、Mark Text）的导出能力差异巨大。Typora 的「导出」→ HTML 输出中等但样式分离到 <style> 标签，不适合公众号。Obsidian 默认无导出需要插件，官方「Markdown Exporter」适合 CMS。Mark Text 导出最简陋。对于程序员推荐用 Node.js 库 marked + 自定义渲染器，这样可以灵活地根据场景（公众号、邮件、网站）调整输出。专业级方案如 MJML（邮件）和「Markdown 转公众号 HTML」服务也值得投入。

Markdown 源文本中如果包含 HTML 片段（如 <script>alert(1)</script>），直接转换可能造成 XSS 漏洞。必须用 DOMPurify 等库清理。配置 ALLOWED_TAGS 和 ALLOWED_ATTR 时，注意 style 属性既能解决样式问题，又增加了风险。只有在确定样式来自可信源时才开放。对于公众号场景，可以编写自定义的样式注入器，既保证排版效果，又防止恶意脚本。测试时务必用含 XSS payload 的 Markdown 验证清理效果。