Skip to content

图片

虽然图片是 Markdown 的一等公民,也是核心语法的一部分,但在处理图片时可能会遇到一些困难。Material for MkDocs 使得处理图片更加舒适,提供了图片对齐和图片标题的样式。

配置

通过以下配置,可以使图片对齐、给图片添加标题(将其呈现为图表),以及标记大图片进行延迟加载。在mkdocs.yml中添加以下行:

markdown_extensions:
  - attr_list
  - md_in_html

查看附加的配置选项:

灯箱效果

0.1.0 · 插件

如果您想要在文档中添加图像缩放功能,glightbox插件是一个很好的选择,因为它与 Material for MkDocs 完美集成。使用pip安装插件:

pip install mkdocs-glightbox

然后,在mkdocs.yml中添加以下行:

plugins:
  - glightbox

我们建议查看可用的配置选项

使用方法

图片对齐

当启用[属性列表]时,可以通过在align属性中添加相应的对齐方向来对齐图片,例如align=leftalign=right

左对齐的图片
![图片标题](https://dummyimage.com/600x400/eee/aaa){ align=left }

图片标题

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

右对齐的图片
![图片标题](https://dummyimage.com/600x400/eee/aaa){ align=right }

图片标题

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

如果在图片旁边渲染文本的空间不足,图片将会拉伸到视口的整个宽度,例如在移动视口上。

为什么没有居中对齐?

align 属性不允许居中对齐,这就是为什么Material for MkDocs不支持此选项的原因。1 相反,可以使用图片标题语法,因为标题是可选的。

图片标题

遗憾的是,Markdown 语法不支持图片标题,但可以始终使用[在 HTML 中使用 Markdown]扩展和字面的figurefigcaption标签:

带标题的图片
<figure markdown>
  ![图片标题](https://dummyimage.com/600x400/){ width="300" }
  <figcaption>图片标题</figcaption>
</figure>
图片标题

图片延迟加载

现代浏览器通过loading=lazy指令提供了原生支持图片延迟加载,在不支持的浏览器中会降级为急加载:

延迟加载的图片
![图片标题](https://dummyimage.com/600x400/){ loading=lazy }

亮色和暗色模式

8.1.1

如果您添加了一个颜色调色板切换,并且想要为亮色和暗色模式显示不同的图片,可以在图片 URL 后面添加#only-light#only-dark哈希片段:

亮色和暗色模式下不同的图片
![图片标题](https://dummyimage.com/600x400/f5f5f5/aaaaaa#only-light)
![图片标题](https://dummyimage.com/600x400/21222c/d5d7e2#only-dark)

塞尔达亮世界 塞尔达暗世界

使用自定义颜色方案时的要求

内置的颜色方案定义了上述哈希片段,但如果您使用自定义颜色方案,还需要根据是亮色还是暗色方案,将以下选择器添加到您的方案中:

[data-md-color-scheme="custom-light"] img[src$="#only-dark"],
[data-md-color-scheme="custom-light"] img[src$="#gh-dark-mode-only"] {
  display: none; /* 在亮色模式中隐藏暗色图片 */
}
[data-md-color-scheme="custom-dark"] img[src$="#only-light"],
[data-md-color-scheme="custom-dark"] img[src$="#gh-light-mode-only"] {
  display: none; /* 在暗色模式中隐藏亮色图片 */
}

请记得将 "custom-light""custom-dark" 改为您方案的名称。


  1. 您可能还注意到,align 属性已在 HTML5 中作为弃用属性,所以为什么还要使用它呢?主要原因是可移植性 - 它仍然被所有浏览器和客户端支持,并且很不可能被完全删除,因为许多旧网站仍在使用它。这确保了在 Material for MkDocs 生成的网站之外查看带有这些属性的 Markdown 文件时的一致外观。