Markdown: Markdown 嵌入 HTML 的方法
Markdown 不是万能的——当语法不够用时，直接写 HTML 就好。
1. 你将学到
- Markdown 中嵌入 HTML 的基本规则
- 内联 HTML 与块级 HTML 的区别
- 常见用 HTML 补充的场景
- HTML 与 Markdown 的边界情况
- 安全性与兼容性注意事项
2. 一个前端开发者的真实故事
(1) 痛点：Markdown 的限制卡住了需求
Lisa 在为公司写技术文档，需要在一个表格单元格中展示带颜色的状态标签（如红色"失败"、绿色"通过"）。Markdown 表格不支持背景色和文字颜色。她尝试用各种 Markdown 技巧绕过，浪费了 2 小时，最终不得不截了一张图片贴上，但图片无法被搜索到。
(2) 解法：在 Markdown 中直接写 HTML
老员工 Tom 告诉她："Markdown 里可以写 HTML 啊。"Lisa 用 <span> 标签加 style 属性实现了彩色标签。既不用截图、文字也能被搜索到，而且代码只多了几行 HTML。
MARKDOWN
| 测试用例 | 状态 |
|:---------|:-----|
| 用户登录 | <span style="color: green;">✅ 通过</span> |
| 支付接口 | <span style="color: red;">❌ 失败</span> |
3. Markdown 中的 HTML 规则
Markdown 的设计哲学是"可以作为 HTML 的简化写法"。因此，它天然支持在文档中嵌入 HTML：
graph TB
A[Markdown 文档] --> B[Markdown 语法]
A --> C[HTML 语法]
B --> D[标题/列表/表格等]
C --> E[块级 HTML]
C --> F[内联 HTML]
E --> G[div/table/pre]
F --> G[span/img/br]
| HTML 类型 | 特点 | 示例 |
|---|---|---|
| 内联 HTML | 在 Markdown 段落内直接写 | <span style="color:red">文字</span> |
| 块级 HTML | 独立成块，前后空行 | <div>内容</div> |
| 块级内的 Markdown | 块级 HTML 内 Markdown 语法可能不生效 | <div>**加粗** 可能无效</div> |
(1) 内联 HTML
HTML
这是一段文字，里面有 <span style="color: red;">红色文字</span> 和
<strong>加粗文字</strong>（用 HTML 标签实现）。
按 Ctrl + <br> 换行（<br> 是 HTML 标签）。
▶ 示例：用 HTML 实现 Markdown 做不到的效果
HTML
这是普通 Markdown 里的文字。
<kbd>Ctrl</kbd> + <kbd>S</kbd> 保存文件。
升级到 <abbr title="Version 3.0">v3.0</abbr> 版本。
⚠️ 注意： 在块级 HTML 标签内，标准 Markdown 语法（如
**加粗**）通常不会解析。你需要直接用 HTML 标签：<strong>加粗</strong>。
(3) 常见块级 HTML 用法
HTML
<!-- 自定义容器 -->
<div style="border: 1px solid #ddd; padding: 16px; border-radius: 8px;">
<h3>重要更新</h3>
<p>系统将于本周末进行维护。</p>
</div>
<!-- 多列布局 -->
<div style="display: flex; gap: 16px;">
<div style="flex: 1;">左列内容</div>
<div style="flex: 1;">右列内容</div>
</div>
<!-- 带样式的表格 -->
<table>
<tr>
<th style="background: #4CAF50; color: white;">名称</th>
<th>价格</th>
</tr>
<tr>
<td>商品 A</td>
<td>$29</td>
</tr>
</table>
5. 常见的 HTML 补充场景
| 场景 | Markdown 限制 | HTML 解决方式 |
|---|---|---|
| 文字颜色 | ❌ 不支持 | <span style="color:red">文字</span> |
| 图片尺寸 | ❌ 不支持 | <img src="url" width="200"> |
| 新标签页打开链接 | ❌ 不支持 | <a href="url" target="_blank">文字</a> |
| 单元格合并 | ❌ 不支持 | <td colspan="2">合并</td> |
| 自定义样式 | ❌ 不支持 | <div style="...">内容</div> |
| 表格内换行 | ❌ 不支持 | <br> 标签 |
▶ 示例：HTML 实现 Markdown 做不到的排版
HTML
<!-- 新标签页打开 -->
<a href="https://example.com" target="_blank">在新窗口打开</a>
<!-- 自定义尺寸图片 -->
<img src="logo.png" width="150" alt="Logo" style="border-radius: 8px;">
<!-- 按键效果 -->
<kbd>Enter</kbd> 或 <kbd>Ctrl</kbd> + <kbd>V</kbd>
<!-- 带背景色的提示 -->
<blockquote style="background: #fff3cd; border-left-color: #ffc107;">
这是一个自定义样式的提示框。
</blockquote>
💡 提示： 这些都是 Markdown 本身不支持的场景。合理使用 HTML 可以让你的文档更专业。但不要过度——80% 的内容用标准 Markdown 就够了。
6. HTML 与 Markdown 的边界
(1) 块级 HTML 内的 Markdown 通常不解析
HTML
<div>
**这段文字不会加粗**（在 div 内 Markdown 语法失效）
<strong>这段文字用 HTML 加粗</strong>
</div>
例外：某些解析器（如 Pandoc）支持在 HTML 标签内继续解析 Markdown，但 GFM（GitHub）不支持。为安全起见，HTML 标签内全程使用 HTML 语法。
(2) 内联 HTML 中的 Markdown
HTML
<span style="color: red;">**这段文字在部分解析器中会加粗**</span>
⚠️ 注意： 各解析器行为不一致，建议在 HTML 标签内统一用 HTML 语法，不要混用 Markdown。
▶ 示例：安全 vs 不安全混用
MARKDOWN
✅ 安全：
- 正文写 Markdown：**加粗**
- 需要自定义时写 HTML：<span style="color: red;">红色</span>
❌ 不安全：
<div style="padding: 8px;">
**这段加粗在 GitHub 上不会生效**
</div>
7. 安全性与兼容性
(1) 不要做
HTML
❌ 不安全：<script>alert('XSS')</script>
❌ 不安全：<img src="x" onerror="alert('攻击')">
❌ 不安全：<iframe src="https://恶意网站.com"></iframe>
⚠️ 注意： GitHub 等平台会自动过滤 XSS 攻击代码，不会执行
<script> 和事件处理器。但从 Markdown 源文件导出到其他平台时，应避免嵌入不安全 HTML。
(2) HTML 兼容性检查
HTML
<!-- ✅ 跨平台兼容 -->
<strong>加粗</strong>
<em>斜体</em>
<kbd>按键</kbd>
<br>
<hr>
<!-- ⚠️ 部分平台不兼容 -->
<details><summary>折叠内容</summary>隐藏文字</details>
<mark>高亮文字</mark>
💡 提示： 如果你的 Markdown 需要在不同平台（GitHub、GitLab、本地预览、博客）之间迁移，尽量少用 HTML。HTML 越多，兼容性风险越大。
8. 完整示例：HTML 增强的 Markdown 文档
TEXT
📖 仅展示
HTML 增强后的 Markdown 文档效果：
产品更新日志 v3.2：
- 绿色背景提示框：显示更新概要
- HTML 表格：模块/状态/负责人（状态带颜色）
- 按键标签：F5 刷新
- Bash 代码块：安装命令 npm install my-app@latest
- 邮箱链接：support@example.com（mailto 协议）
预期效果：一份结合了 Markdown 和 HTML 的产品日志——Markdown 处理标准结构，HTML 处理颜色、按键样式和自定义容器。
❓ 常见问题
Q 在 Markdown 中用 HTML 是好习惯吗？
A 适度使用。80% 的内容用标准 Markdown，只有 Markdown 不支持的功能（颜色、尺寸、新标签页）时才用 HTML。HTML 越多，文档的可移植性越差。
Q GitHub 支持哪些 HTML 标签？
A GitHub 支持大部分安全的内联和块级 HTML 标签，但会过滤
<script>、<iframe> 等不安全标签和事件处理器（如 onclick）。Q HTML 标签内的 Markdown 语法为什么不生效？
A 因为 Markdown 解析器在处理 HTML 块时，会跳过内部的 Markdown 解析。这是规范行为。解决方式是在 HTML 块内全部使用 HTML 语法。
Q 块级 HTML 前后必须空行吗？
A 必须。没有空行的块级 HTML 可能导致渲染异常——Markdown 解析器可能无法正确识别 HTML 块的边界。
Q 在 HTML 中可以使用 CSS 类名吗？
A 可以，但类名只在你的目标平台有对应 CSS 规则时生效。在 GitHub 上，自定义类名无效。在自定义网站中，你可以定义自己的 CSS 样式。
📖 小节
- Markdown 原生支持嵌入 HTML，内联和块级均可
- 块级 HTML 前后须有空行，内部 Markdown 语法通常失效
- HTML 补充场景：颜色、尺寸、新标签页、单元格合并、按键样式
- 避免嵌入不安全 HTML（
<script>、事件处理器） - HTML 越多，跨平台兼容性越差，适度使用
- 80% 的内容用标准 Markdown 足够，HTML 只用于特殊需求
📝 作业
-
基础题：写一段 Markdown，用
<span>标签将一句话中的某个词改为红色，并用<kbd>标签显示 "Ctrl+S" 快捷键。 -
进阶题：创建一个自定义样式的提示框（用
<div>加背景色和边框），里面包含一段文字和一个链接。验证在 VS Code 和 GitHub 上的效果差异。 -
挑战题：用 HTML 表格（含
<thead>和<tbody>）替代 Markdown 表格，实现表头有背景色、首行合并单元格的效果。然后将这个 HTML 表格和 Markdown 表格放在同一文档中，对比渲染效果。
