简要对比
当写作速度、源文本可读性、可移植性和版本控制差异最重要时，选择 Markdown。当文档需要 Markdown 无法表达的语义或组件，或者你直接拥有渲染后的网页时，选择 HTML。
| 关注点 | Markdown | HTML |
|---|---|---|
| 源文本可读性 | 对常见文档很高 | 内容周围有更多标记 |
| 呈现控制 | 交由渲染器决定 | 可通过 CSS 精细控制 |
| 文档词汇 | 小而克制 | 广泛的语义元素集合 |
| 可移植性 | 在通用语法内很强 | 在 Web 上很强 |
| 交互性 | 通常没有 | 可通过脚本和组件实现 |
| 安全面 | 取决于渲染器 | 活动内容需要严格控制 |
Markdown 的优势
Markdown 让作者专注于文档的层级结构和文字内容。标题就是标题，无需纠结类名、间距 token 或响应式断点。这让日常技术写作更快，评审差异也更清爽。
代价是渲染器拥有最终决定权。同一个表格或任务列表在 GitHub、编辑器、静态站点生成器中的显示效果可能不同，某些扩展也并非处处可用。
HTML 的优势
HTML 可以表示导航、图表、详情面板、表单、定义、媒体以及丰富的无障碍关系，这些是核心 Markdown 无法表达的。结合 CSS，它可以支持精确的布局和设计体系。
这种能力也带来责任。作者或组件系统必须产出合法的语义、友好的键盘交互、响应式样式和安全的内容边界。来自不可信文档的原始 HTML 未经净化绝不能注入。
大多数文档系统两者兼用
常见的管线把文章以 Markdown 存储，转换为 HTML，再应用共享组件和 CSS。作者获得可读的源文本，网站则获得导航、语法高亮、响应式布局和无障碍特性。
有些系统允许在 Markdown 中使用原始 HTML。请谨慎使用这个逃生舱口：它会降低可移植性，并可能扩大安全面。当发布平台提供了有文档的组件或扩展时，优先使用它们。
等价的标题与链接Markdown
Markdown: ## API reference [Read the schema](/schema) HTML: <h2>API reference</h2> <a href="/schema">Read the schema</a>
把 HTML 转换为 Markdown 会有意造成信息丢失
语义化的标题、段落、链接、列表、代码和简单表格通常都有清晰的对应物。而 CSS 布局、类名、脚本、表单和自定义组件则没有。好的转换会保留可读的文档，把 Web 应用的部分留在身后。
转换后，请检查相对链接、图片引用、代码围栏以及任何原始片段。编辑器预览应该净化不可信的输出，但发布环节仍然需要自己的内容策略。