图片¶

¥Images¶

虽然图像是 Markdown 的“一等公民”，也是核心语法的一部分，但使用起来却可能比较困难。Material for MkDocs 提供了图像对齐和图像标题的样式，让图像处理更加便捷。

¥While images are first-class citizens of Markdown and part of the core syntax, it can be difficult to work with them. Material for MkDocs makes working with images more comfortable, providing styles for image alignment and image captions.

配置¶

¥Configuration¶

此配置添加了对齐图像、为图像添加标题（将其渲染为图形）以及将大图像标记为延迟加载的功能。将以下几行添加到mkdocs.yml中：

¥This configuration adds the ability to align images, add captions to images (rendering them as figures), and mark large images for lazy-loading. Add the following lines to mkdocs.yml:

markdown_extensions:
  - attr_list
  - md_in_html
  - pymdownx.blocks.caption

查看其他配置选项：

¥See additional configuration options:

¥Lightbox¶

0.1.0 glightbox

¥0.1.0 glightbox

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

¥If you want to add image zoom functionality to your documentation, the glightbox plugin is an excellent choice, as it integrates perfectly with Material for MkDocs. Install it with pip:

pip install mkdocs-glightbox

然后，将以下行添加到mkdocs.yml ：

¥Then, add the following lines to mkdocs.yml:

plugins:
  - glightbox

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

¥We recommend checking out the available configuration options.

用法¶

¥Usage¶

图像对齐¶

¥Image alignment¶

启用属性列表后，可以通过align属性添加相应的对齐方向来对齐图像，即align=left或align=right ：

¥When Attribute Lists is enabled, images can be aligned by adding the respective alignment directions via the align attribute, i.e. align=left or align=right:

LeftRight

Image, aligned to left

![Image title](https://dummyimage.com/600x400/eee/aaa){ align=left }

Image title

Lorem ipsum dolor sat amet，consectetur adipiscing elit。 Nulla et euismod nulla。 Curabitur feugiat、tortor non consequat finibus、justo purus auctor Massa、nec semper lorem quam in Massa。

¥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.

Image, aligned to right

![Image title](https://dummyimage.com/600x400/eee/aaa){ align=right }

Image title

Lorem ipsum dolor sat amet，consectetur adipiscing elit。 Nulla et euismod nulla。 Curabitur feugiat、tortor non consequat finibus、justo purus auctor Massa、nec semper lorem quam in Massa。

¥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.

如果没有足够的空间来呈现图像旁边的文本，则图像将拉伸到视口的整个宽度，例如在移动视口上。

¥If there's insufficient space to render the text next to the image, the image will stretch to the full width of the viewport, e.g. on mobile viewports.

Why is there no centered alignment?

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

¥The align attribute doesn't allow for centered alignment, which is why this option is not supported by Material for MkDocs.¹ Instead, the image captions syntax can be used, as captions are optional.

图片说明¶

¥Image captions¶

遗憾的是，Markdown 语法不提供对图像标题的原生支持，但始终可以使用带有文字figure和figcaption标签的 HTML 扩展中的 Markdown ：

¥Sadly, the Markdown syntax doesn't provide native support for image captions, but it's always possible to use the Markdown in HTML extension with literal figure and figcaption tags:

Image with caption

<figure markdown="span">
  ![Image title](https://dummyimage.com/600x400/){ width="300" }
  <figcaption>Image caption</figcaption>
</figure>

但是， Caption提供了一种替代语法来向任何 Markdown 块元素（包括图像）添加标题：

¥However, Caption provides an alternative syntax to add captions to any Markdown block element, including images:

Image with caption

![Image title](https://dummyimage.com/600x400/){ width="300" }
/// caption
Image caption
///

图像延迟加载¶

¥Image lazy-loading¶

现代浏览器通过loading=lazy指令为延迟加载图像提供本机支持，在不支持的浏览器中，该指令将降级为立即加载：

¥Modern browsers provide native support for lazy-loading images through the loading=lazy directive, which degrades to eager-loading in browsers without support:

Image, lazy-loaded

![Image title](https://dummyimage.com/600x400/){ loading=lazy }

明暗模式¶

¥Light and dark mode¶

8.1.1

¥8.1.1

如果您添加了调色板切换，并希望为明暗配色方案显示不同的图像，则可以将#only-light或#only-dark哈希片段附加到图像 URL：

¥If you added a color palette toggle and want to show different images for light and dark color schemes, you can append a #only-light or #only-dark hash fragment to the image URL:

Image, different for light and dark mode

![Image title](https://dummyimage.com/600x400/f5f5f5/aaaaaa#only-light)
![Image title](https://dummyimage.com/600x400/21222c/d5d7e2#only-dark)

Zelda light world Zelda dark world

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

¥Requirements when using custom color schemes

内置配色方案定义了前面提到的哈希片段，但如果您使用自定义配色方案，则还必须向方案中添加以下选择器，具体取决于它是亮色方案还是暗色方案：

¥The built-in color schemes define the aforementioned hash fragments, but if you're using custom color schemes, you'll also have to add the following selectors to your scheme, depending on whether it's a light or dark scheme:

Custom light schemeCustom dark scheme

[data-md-color-scheme="custom-light"] img[src$="#only-dark"],
[data-md-color-scheme="custom-light"] img[src$="#gh-dark-mode-only"] {
  display: none; /* Hide dark images in light mode */
}

[data-md-color-scheme="custom-dark"] img[src$="#only-light"],
[data-md-color-scheme="custom-dark"] img[src$="#gh-light-mode-only"] {
  display: none; /* Hide light images in dark mode */
}

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

¥Remember to change "custom-light" and "custom-dark" to the name of your scheme.

你可能也意识到了， align属性自 HTML5 起就被弃用了，那为什么还要使用它呢？主要原因是可移植性——它仍然受所有浏览器和客户端支持，而且不太可能被完全移除，因为许多老网站仍在使用它。这确保了在 Material for MkDocs 生成的网站之外查看带有这些属性的 Markdown 文件时，外观保持一致。↩

图片¶

配置¶

灯箱¶

用法¶

图像对齐¶

图片说明¶

图像延迟加载¶

明暗模式¶