纸上得来终觉浅，绝知此事要躬行。

正确标识图

在 Markdown 中插入一张图片需要使用如下语法：

![alt](src)

不过貌似大部分人会把 alt 部分留空，这是不够理想的。一个具有完整语义元素的图片至少需要一个 src 属性和一个 alt 属性；src 用于指定加载图像的 URI, 而 alt 属性则用于说明图片的内容。

alt 部分应该写什么？

alt 部分应该对图片做出功能性描述。

想象你在给一位盲人朋友描述图片里的内容，这就是应该写到 alt 里的内容。总得来说，图片描述应该满足以下要求：

• 用词简练
• 功能优先于内容
• 先总体后局部
• 描述图片中的内容而非图片本身
  • 尤其是不要写「关于某某的图片」，直接写「某某」就足够了
• 不要携带无法从图片中推断出的信息

如果图片中包含文字且对于图片内容的解读有影响，则也需要转写图片内的文字。

我一定要给每张图片都写上几百字的小作文嘛？

当然不用。就像我们不会一股脑地将所有信息全部罗列出来一样，图片描述也不需要将图片中的所有内容都全部描述出来以至于你可以直接把这段文字当做提示词喂给图片生成 AI 然后得到一张看起来和原图几乎一样但是又各种不对味的图片。

图片描述需要和你所要表达的内容相辅相成。我们应将图片描述视作正文的扩展，这样即使你在一个没有网络的环境里或者在纯文本环境下也可以通过图片描述文字来理解图片所需要呈现的信息。试考虑这样一张图片：

在不同的场景下会需要编写不同的图片说明。WebAIM 的指南详细地列出了各种情况下应该如何编写图片的描述文字。不过，作为博客文章，我们一般只需要考虑以下 4 种可能的场景。

场景 1: 独立图片

图片单独地作为正文出现，周围没有说明文字，如同悬挂在展厅里的一幅画。

在这种情况下，你可能确实需要写一段话来详细地描述图片的内容，例：

格蕾丝・霍珀（Grace Hopper）的正式半身军装肖像照，面向镜头拍摄，背景为纯净浅灰白色墙面。

画面左侧竖立着一面美国国旗，蓝底白星、红白条纹清晰可见，旗杆垂挂两根金黄色流苏穗带。

照片中心是年长白人女性格蕾丝・霍珀。她一头浅金色短发收拢在海军军官帽下。头戴美国海军黑白配色军官大檐帽：帽檐与帽侧为黑色，帽顶正面是米白色，帽子正中饰有金色刺绣徽章，图案为白头海雕、船锚与枝叶纹样。

她戴着一副眼镜，镜框上半部分深灰黑色，下半圈为浅米黄色透明材质。脸上布满皱纹，神情严肃沉稳，直视前方镜头。

她身着深藏青色美国海军军官礼服外套，外套配有圆形金色纽扣。内搭白色翻领衬衫，系黑色领结。

右胸（画面左侧）缝制长方形姓名铭牌，印有 “COMO HOPPER” 字样；左胸（画面右侧）整齐排列多条色彩缤纷的勋章勋表，带有红、蓝、金、粉等各色饰条。

整体画面光线柔和均匀，是官方标准军装人像摄影，氛围庄重正式。

格蕾丝・霍珀是著名数学家、计算机先驱、美国海军少将，编译器概念的开创者。

场景 2: 作为说明性图片出现

图片作为正文的补充出现。

这种情况下，只需要描述正文中所没有的内容即可；比如正文中已经对人物有了详细的生平介绍，则说明文字只需要描述图片中的内容，例：

格蕾丝・霍珀的官方半身军装肖像。画面左侧是带有金色流苏的美国国旗，背景为素净浅白墙面。年长的她正视镜头，头戴美国海军军官帽，佩戴眼镜；身着深藏青色海军制服，内搭白衬衫、黑色领结，制服上配有姓名牌与一排彩色勋表，神态庄重沉稳。

场景 3: 作为功能性图片出现

图片参与到某种页面的交互功能中，如作为链接或按钮的一部分。

这种情况下，则需要优先描述图片的功能。注意到图片的功能并不是要写「这个图片是一个链接」，屏幕阅读器已经会先朗读类似「图片，链接，……」了，所以我们需要描述的是除了导航作用以外的功能。试考虑这样一个结构：

这里的 PDF 图标的功能是表示这个文件是一份 PDF 文件，则其图片描述就应该是「PDF 文件」。

场景 4: 作为装饰性图片出现

一些纯粹装饰性的图片，尤其是那种即使移除了对于正文也没有任何影响的图片，反而应该留一个空白的 alt 属性。这样，屏幕阅读器就会略过这些装饰图片。

对于分隔线等装饰性图片，应该优先考虑使用 CSS 的 background-image 属性来为不携带语义信息的元素指定图片，这样就不需要额外地考虑使用 <img> 标签所蕴含的潜在语义问题。

添加图标题

如果你受过写论文或者毕业设计说明的毒打，你可能会想着给图片添加一个标题。在 HTML 中，这样一个带着标题的图是一个 <figure>:

<figure>
    <img src="https://example.com/example.jpg" alt="Example image">
    <figcaption></figcaption>
</figure>

但是 Markdown 并不原生支持生成 <figcaption>, 所以我们需要通过一些手段来扩展 Markdown. 对于 11ty 方案来说，最常用的软件包是 markdown-it-image-figures.

从 NPM 召唤这个包：

npm i markdown-it-image-figures

然后修改 eleventy.config.js 导入：

import mdfg from 'markdown-it-image-figures'

export default function (eleventyConfig) {
  eleventyConfig.amendLibrary('md', (md) => {
    md.use(mdfg, {
      figcaption: true, // 将图片的 title 属性作为 <figcaption> 元素的内容
      lazy: true,  // 是否懒加载图片
      async: true, // 是否允许异步加载图片
    })
  })
}

然后我们就可以通过 Markdown 的图片 title 语法来指定一张图的标题了：

![alt](src "title")

图标题的自动编号

有了图标题，自然也得给图进行编号。得益于 CSS 3 中的计数器变量，我们不需要挨个手打图 1 图 2 图 3, 只需要简单几行 CSS 就搞定了：

body { counter-reset: figure-counter; }
figure { counter-increment: figure-counter; }
figcaption::before {
  content: "图 " counter(figure-counter) " ";
}

不过，要在正文里像 TeX \TeX 那样拿到图片的编号目前似乎还比较困难，而且目前似乎没有任何现成的解决方案，所以大概率还是需要用 Pandoc 或者 Bookdown 来实现这个效果——这就太沉了。

有了图标题，还需要写图片的描述文字么？

需要。图标题的作用是给图片赋予一个名字、为图片添加额外的说明（比如对图表数据的解读或者评论），以及添加来源或者版权信息的；而图片描述文字则是关于图片内容的描述。二者的作用理论上是不重叠的，所以最好不要逃课。

实在是嫌麻烦，可以选择不写图标题，毕竟并不是所有文章都得当论文来写。

正确标识表

Markdown 产生的表格一般是有正确的语义标签的：完整的 <thead> 和 <tbody> 元素用于描述表头。但是如果你的表需要将第一列作为表头的话，除了手写 HTML 使用 <th> 标签以外似乎并没有太好的方法。

添加表标题

表标题在 HTML 中使用 <caption> 标签，其语法如下：

<table>
  <caption>Table caption</caption>
  <thead>
    <!-- 略 -->
  </thead>
  <tbody>
    <!-- 略 -->
  </tbody>
</table>

如果不太想手写 HTML 的话，在 11ty 中，可以使用软件包 markdown-it-table-captions 为表格添加标题。

从 NPM 中召唤这个包：

npm i markdown-it-table-captions

然后修改 eleventy.config.js 导入：

import mdtbl from 'markdown-it-table-captions'

export default function (eleventyConfig) {
  eleventyConfig.amendLibrary('md', (md) => {
    md.use(mdtbl)
  })
}

这个插件会识别表格紧贴的段落是否以 Table: 开头，并将其作为表格标题。没错，必须是 Table:, 必须是这个大小写，必须是英文冒号，冒号后面必须跟着一个英文空格，否则不管用。用例如下：

| 项目 | 最小值 | 典型值 | 最大值 |
| --- | --- | --- | --- |
| 高电平阈值 (V) | - | 2.9 | - |
| 低电平阈值 (V) | - | 0.3 | - |
| 高电平保持时间 (ns) | 7.1 | - | - |
| 低电平保持时间 (ns) | 7.1 | - | - |
| 时钟频率 (MHz) | - | 64 | - |

Table: 设备的电器特性

编译后，便会得到这样一个表格：

<table>
  <caption>设备的电器特性</caption>
  <thead>
    <tr>
      <th>项目</th>
      <th>最小值</th>
      <th>典型值</th>
      <th>最大值</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>高电平阈值 (V)</td>
      <td>-</td>
      <td>2.9</td>
      <td>-</td>
    </tr>
    <tr>
      <td>低电平阈值 (V)</td>
      <td>-</td>
      <td>0.3</td>
      <td>-</td>
    </tr>
    <tr>
      <td>高电平保持时间 (ns)</td>
      <td>7.1</td>
      <td>-</td>
      <td>-</td>
    </tr>
    <tr>
      <td>低电平保持时间 (ns)</td>
      <td>7.1</td>
      <td>-</td>
      <td>-</td>
    </tr>
    <tr>
      <td>时钟频率 (MHz)</td>
      <td>-</td>
      <td>64</td>
      <td>-</td>
    </tr>
  </tbody>
</table>

我们也可以通过同样的 CSS 小技巧来指定表的编号：

body { counter-reset: table-counter; }
table { counter-increment: table-counter; }
table > caption::before {
  content: "表 " counter(table-counter) " ";
}

指定表标题的位置

默认情况下，表标题是出现在表格上面的，不过可能你的学校的习惯是表标题应该出现在表格的下面。令我惊讶的是，CSS 中专门有一个属性来指定表标题的位置：

table > caption {
  caption-side: bottom;
}

这样，即使不调整 <caption> 元素在 <table> 中的位置，浏览器也会自行将标题放在表格的底部了。