陌阡博客

主题

第 11 章：HTML 混合排版 ​

Markdown 语法刻意保持简洁，但总有些排版需求超出其能力范围。好在 Markdown 与 HTML 可以无缝混用——需要什么，直接写 HTML。

学习目标 ​

  • 理解 Markdown 中嵌入 HTML 的规则
  • 掌握常用 HTML 标签在 Markdown 中的应用
  • 了解 HTML 与 Markdown 混用的兼容性边界

11.1 基本规则 ​

Markdown 的核心设计原则之一是：在 Markdown 文档中可以直接写 HTML。这意味着一篇 Markdown 文档完全可以用 HTML 实现任何排版需求。

markdown
# Markdown 标题

这是 Markdown 段落。

<div style="color: red; font-size: 20px;">
  这是 HTML 红色大字。
</div>

这是另一段 Markdown。

HTML 与 Markdown 的边界 ​

规则说明
块级 HTML 内Markdown 语法不解析
行内 HTML 内Markdown 语法不解析
HTML 标签外正常的 Markdown 语法
HTML 属性直接写在标签上
块级 HTML 内：
<div>
    **这不是粗体**  ← Markdown 不解析
</div>

块级 HTML 外：
**这是粗体**  ← Markdown 正常解析

行内 HTML 内：
<span style="color:red">**这不是粗体**</span>

但如果你想在 HTML 内用 Markdown：
<div markdown="1">
    **这是粗体**  ← 部分平台支持 markdown="1"
</div>

⚠️ markdown="1" 属性不是通用标准。GitHub 不支持此属性。需要兼容 GitHub 时，HTML 内的内容只能写纯 HTML。

11.2 常用 HTML 标签 ​

文本样式 ​

html
这是<u>下划线</u>文字。          <!-- Markdown 原生无下划线 -->

这是<mark>高亮</mark>文字。      <!-- GitHub 兼容 -->
这是<ins>插入</ins>文字。        <!-- 语义相当于新增内容 -->
这是<sub>下标</sub>文字。        <!-- H₂O -->
这是<sup>上标</sup>文字。        <!-- E=mc² -->
这是<small>小字</small>文字。    <!-- 注释、免责声明 -->

渲染：这是下划线文字。这是高亮文字。这是插入文字。这是下标文字。这是上标文字。这是小字文字。

折叠面板（Details/Summary） ​

这是 GitHub 上非常实用的功能，可以创建可折叠的内容区：

html
<details>
<summary>点击展开更多信息</summary>

这里是被折叠的内容，可以包含 Markdown 格式的文字、代码块等。

```python
print("在折叠面板里也能放代码")
```

- 甚至可以有列表
- 和其他 Markdown 元素

</details>

⚠️ 注意：在 GitHub 上，<details> 内的 Markdown 语法需要与 HTML 标签之间留一个空行才能正确解析。

图片尺寸与对齐 ​

html
<!-- 设置宽度 -->
<img src="https://example.com/photo.png" width="400" alt="示例图片">

<!-- 居中 -->
<p align="center">
  <img src="https://example.com/photo.png" width="300" alt="居中图片">
</p>

键盘按键 ​

html
按下 <kbd>Ctrl</kbd> + <kbd>C</kbd> 复制内容。

渲染：按下 Ctrl + C 复制内容。

视频嵌入 ​

html
<video width="100%" controls>
  <source src="demo.mp4" type="video/mp4">
  您的浏览器不支持 video 标签。
</video>

音频嵌入 ​

html
<audio controls>
  <source src="audio.mp3" type="audio/mpeg">
  您的浏览器不支持 audio 标签。
</audio>

11.3 复杂表格 ​

当 Markdown 表格不够用时，HTML <table> 是完美的替代方案：

html
<table>
  <thead>
    <tr>
      <th>功能</th>
      <th colspan="2">兼容性</th>
    </tr>
    <tr>
      <th></th>
      <th>桌面端</th>
      <th>移动端</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>导航栏</td>
      <td>✅</td>
      <td>✅</td>
    </tr>
    <tr>
      <td>图表渲染</td>
      <td>✅</td>
      <td>⚠️ 部分支持</td>
    </tr>
    <tr>
      <td rowspan="2">表单</td>
      <td>✅</td>
      <td>✅</td>
    </tr>
    <tr>
      <td>✅</td>
      <td>⚠️</td>
    </tr>
  </tbody>
</table>

这实现了 Markdown 表格无法做到的：

  • colspan：跨列合并（表头 "兼容性" 占两列）
  • rowspan：跨行合并（"表单" 占两行）

11.4 安全考虑 ​

在 GitHub 等平台渲染用户提交的 Markdown 时，出于安全考虑，平台会过滤掉危险的 HTML：

标签/属性GitHub说明
<script>❌ 过滤防止 XSS 攻击
<iframe>❌ 过滤防止嵌入恶意页面
<style>❌ 过滤防止样式注入
onclick 等事件属性❌ 过滤防止执行脚本
class / id❌ 过滤GitHub 不允许自定义 CSS
<div> / <span>✅ 允许基础容器标签
<img>✅ 允许图片标签
<table>✅ 允许复杂表格
<details>✅ 允许折叠面板
<kbd>✅ 允许键盘按键
<sub> / <sup>✅ 允许上下标
<mark> / <ins> / <del>✅ 允许语义化文本

11.5 实践建议 ​

什么时候用 HTML ​

需求MarkdownHTML 替代
调整图片尺寸❌<img width="...">
图片居中/对齐❌<p align="center"><img></p>
合并单元格❌<table> + colspan/rowspan
折叠内容❌<details><summary>
下划线❌<u>
上下标❌<sub> / <sup>
视频/音频嵌入❌<video> / <audio>

什么时候不用 HTML ​

  • 能用 Markdown 原生语法实现的，就用 Markdown——源码更简洁
  • 追求简洁可读的场景——Markdown 的设计初衷
  • 面向纯文本阅读的场景——HTML 标签在纯文本环境不友好

11.6 语法速查 ​

需求HTML 写法平台兼容
下划线<u>文字</u>✅
高亮<mark>文字</mark>✅
上标<sup>文字</sup>✅
下标<sub>文字</sub>✅
键盘按键<kbd>Ctrl</kbd>✅
图片居中<p align="center"><img></p>✅
折叠面板<details><summary>GitHub ✅
视频<video src="file.mp4" controls>✅
复杂表格<table> + colspan/rowspan✅

本章小结 ​

要点说明
混用规则Markdown 中可以任意写 HTML
块级 HTML内部的 Markdown 语法不会解析
GitHub 安全过滤 <script>、<style>、<iframe> 和事件属性
实用标签<details>、<kbd>、<mark>、<table>
使用原则Markdown 能做的用 Markdown，不能的再用 HTML

下一章预告 ​

语法学完了，接下来选一把趁手的兵器——市面上有哪些好用的 Markdown 编辑器？如何把 Markdown 转成 PDF、Word、HTML？

👉 第 12 章：工具链与编辑器

📖本文阅读--次|📊全站访问--次|👥访客--人