不喜欢广告？ 去 无广告 今天
Markdown 实际是什么
Markdown 是一种轻量级的标记语言——你用纯文本编写内容，使用简单的约定（粗体用星号，标题用井号，代码用反引号），然后由解析器将其转换为 HTML。目前没有统一的官方 Markdown 标准；你最终得到的内容取决于所使用的解析器。
最常见的变体：
- CommonMark —— 一个严格且定义明确的标准。最接近“纯 Markdown”的版本。
- GitHub 风格 Markdown（GFM） —— CommonMark 加上表格、任务列表、删除线和自动链接 URL。GitHub 和 GitLab 使用的渲染方式。
- kramdown、Pandoc、MultiMarkdown —— 增强版本，支持脚注、定义列表和 CommonMark 中未包含的自定义属性。
如果你正在编写 README 并期望 GitHub 能正确渲染它，那么你应该使用 GFM 规范。如果你使用的是静态站点生成器，请检查它使用的解析器——在嵌套列表或原始 HTML 处理等边缘情况下，不同解析器可能会有差异。
Markdown 的优势场景
README 文件和开发者文档。 Markdown 是开发者文档的默认格式。GitHub、GitLab、Bitbucket、npm、PyPI 等平台都原生支持 Markdown。虽然用 HTML 编写 README 在技术上是可行的，但对需要编辑文档的贡献者而言，这实际上会带来极大的不便。
Wiki 和变更日志。 扁平化、版本控制的纯文本文件，由人类编辑，且必须保证差异（diff）可读。HTML 内容冗长，会生成无意义的差异。而 Markdown 保持简洁清晰。
文档网站。 像 MkDocs、Docusaurus、Hugo 和 Jekyll 这样的工具会将 Markdown 文件在构建时转换为 HTML。作者编写 Markdown，网站负责最终的展示。
当内容由非开发人员编写时。 Markdown 比 HTML 更容易学习和编写。如果内容流程中包含非前端工程师的撰稿人，Markdown 能显著降低写作门槛。
HTML 的优势场景
邮件。 邮件客户端——特别是 Outlook——对 CSS 的支持非常不一致。HTML 可以让你明确控制布局、字体大小、间距和内联样式。使用 Markdown 转 HTML 渲染的邮件在某些邮件客户端中可能因禁用某些标签或不支持渲染输出而崩溃。
精细的布局和样式。 当你需要特定的列宽、浮动布局或自定义 CSS 类时，Markdown 会显得力不从心。你要么需要混合使用原始 HTML，要么需要与解析器输出进行对抗。
复杂表格。 GFM 表格适用于简单的网格。一旦你需要合并单元格、多行单元格内容或跨列单元格，Markdown 语法就会失效。HTML 是更合适的选择。 <table> 是正确的工具。
内容由 CMS 管理。 大多数 CMS 平台将文章内容存储为 HTML，或使用基于块的编辑器生成结构化的 HTML。将 Markdown 强行塞入这样的流程中，会增加一个转换层，除非 CMS 本身是为 Markdown 设计的，否则这种转换并无明显优势。
总体对比一览
| 用例 | Markdown | HTML | 胜出 |
|---|---|---|---|
| GitHub README | 原生支持 | 冗长且不友好 | Markdown |
| 邮件模板 | 不一致 | 完整控制 | HTML |
| 文档网站 | 原生支持，需构建步骤 | 需要构建步骤 | Markdown |
| 复杂表格 | 有限的 | 完整控制 | HTML |
| API 响应体 | 常见模式 | 可用但冗长 | Markdown |
| CMS 内容 | 需要转换 | 原生支持 | HTML |
| 变更日志 | 清晰的差异 | 过度复杂 | Markdown |
GFM 相比 CommonMark 的新增功能
GitHub 风格 Markdown 增加了开发者经常用到的功能。以下是一个 GFM 表格和任务列表的示例——这两个功能在 CommonMark 中并不存在：
## GFM Table
| Name | Role | Status |
|----------|----------|---------|
| Alice | Author | Active |
| Bob | Reviewer | Pending |
## GFM Task List
- [x] Write draft
- [x] Add code examples
- [ ] CMO review
- [ ] Schedule publish这些内容在纯 CommonMark 解析器中都无法渲染。如果你的文档工具链使用的是不带扩展的 CommonMark，这些块将直接显示为原始文本。请始终确保你的语法与所使用的解析器匹配。
混合 Markdown 和 HTML
大多数 Markdown 解析器允许在文本中插入原始 HTML。CommonMark 默认支持，GFM 也支持，但会进行一些清理。这意味着你可以在 Markdown 文件中插入 <div> 或 <table> 以表达语法无法实现的内容。
通常会失败的情况：在 HTML 块内部嵌套 Markdown。如果你打开一个 <div> 并在其中写入 Markdown，大多数解析器将不会处理这些 Markdown 内容——它们会将整个块当作原始 HTML 处理。如果你需要在 HTML 包装器中嵌入 Markdown 内容，必须依赖解析器明确支持（kramdown 提供了相应的属性；大多数其他解析器没有）。 markdown="1" 经验法则：仅在需要结构重写时使用 HTML 块。不要尝试在 Markdown 文件中用 HTML 写整个部分——一旦达到这种程度，直接写 HTML 更为合适。
API 响应体中的 Markdown
一种常见且实用的模式：API 在响应字段中返回 Markdown 字符串。Notion 的富文本 API、Slack 的块套件、各种帮助台和 CMS API 都会发送 Markdown 内容，客户端需要负责渲染这些内容。
为什么？Markdown 紧凑、可读性强，且便于编辑器操作。存储
比存储 **bold text** 更便宜且更清晰，同时保持数据格式与任何特定的 HTML 结构解耦。如果你正在构建一个返回人类可读内容的 API，将 Markdown 存储在字符串字段中是一个合理的选择——只需明确说明你使用的具体变体即可。 <strong>bold text</strong>安全渲染 Markdown
在前端直接渲染用户提供的 Markdown 而不进行过滤，会构成 XSS 攻击向量。一个支持原始 HTML 的 Markdown 解析器会轻易地将嵌入在用户内容中的
传递给前端。 <script>alert('xss')</script> 解决方案：对渲染输出进行清理
而不是对 Markdown 输入进行清理。DOMPurify（浏览器）、sanitize-html（Node.js）或 Bleach（Python）等库可以移除渲染 HTML 中的危险标签和属性，同时保留安全的格式。切勿在没有经过清理处理的情况下直接将未验证的 Markdown 渲染到 DOM 中。解析器不是你的安全防线。 浏览器中尝试如果你希望实验 Markdown 渲染——测试 GFM 语法、预览表格和任务列表的显示效果，或检查原始 HTML 在 Markdown 中的行为——可以使用
IO Tools Markdown 编辑器
它可以在浏览器中直接运行，无需安装。它是一个快速的在线 Markdown 编辑器，可用于起草文档、预览 README 文件，或在最终确定格式前测试解析器行为。 Markdown 与 HTML：在文档、README 和 API 中何时使用 Markdown 与 HTML：在文档、README 和 API 中何时使用
