图片和图表#
图片#
MyST Markdown 提供了几种不同的语法，用于在文档中插入图片，如下所述。
首先是标准的 Markdown 语法，通过这种方式：
会产生：
这会将图片正确复制到构建文件夹，并在所有输出格式（HTML、TeX 等）中渲染它。然而，它在可配置性方面有限制。例如，无法通过这种语法设置图片的宽度。
正如在这一节中讨论的，MyST 允许使用如 image 和 figure 这样的指令（参见 Sphinx 文档了解可用选项）。
例如：
```{image} ../images/fun-fish.png
:alt: fishy
:class: bg-primary mb-1
:width: 200px
:align: center
```
将包含以下 自定义 图片：
这些指令允许你使用指令参数控制图片的各个方面。
原始 HTML 图片#
上述图片语法提供了更多的自定义性，但请注意，这种语法在常见的 Markdown 查看器（例如在 GitHub 上查看文件时）中不会显示图片。
一种解决方法是直接使用 HTML，而 MyST 可以通过 html_image 扩展直接解析 HTML 图片。
Warning
使用原始 HTML 通常是一个糟糕的选择（参见此解释），所以在这样做之前要小心！
要解析原始 HTML 图片语法，请在 _config.yml 中的扩展列表中启用 html_image 扩展：
parse:
myst_enable_extensions:
# 不要忘记列出你想要启用的其他扩展，
# 包括那些默认启用的扩展！参见这里：https://jupyterbook.org/en/stable/customize/config.html
- html_image
HTML 图片将被解析为任何其他图片。例如：
<img src="../images/fun-fish.png" alt="fishy" class="bg-primary" width="200px">
将正确渲染：
这也将在 PDF LaTeX 构建中输出！
允许的属性与 image 指令相同：src、alt、class、width 和 height。任何其他属性将被忽略。
支持的图片格式#
标准的光栅化图片格式，如 .png 和 jpg，对 HTML 和 LaTeX/PDF 输出格式都支持。相比之下，矢量格式如 .svg、.pdf 和 .eps 通常是构建器特定的。参见每个 Sphinx 构建器的 supported_image_types 规范这里。
为了支持多个构建器，Jupyter Book 允许你使用 * 星号作为扩展名。例如，对于 HTML：
<img src="../images/fun-fish.*" alt="fishy" class="bg-primary mb-1" width="200px">
所有匹配所提供模式的图片将被搜索，每个构建器从可用候选中选择最佳图片。
上述代码生成了以下图片：
你可以使用像 imagemagick 这样的工具，在构建你的书之前将图片转换为多种格式。
或者，你可能希望查看这些 Sphinx 扩展：
图表#
MyST Markdown 还允许你在页面中包含 图表。图表类似于图片，但它们更容易在书的其他地方引用，并且包含如标题等内容。要包含一个图表，使用以下语法：
```{figure} ../images/C-3PO_droid.png
---
height: 150px
name: directive-fig
---
这是我的图表标题！
```
这将产生以下内容：
Fig. 2 这是我的图表标题！#
Note
你还可以包含由笔记本中的代码生成的图表。
要做到这一点，参见 content:executable:output-insert。
Markdown 图表#
Markdown 图表结合了冒号样式提示和HTML 图片解析，以产生一种“Markdown 友好”的图表语法，其行为与上述 figure 指令相同。
Note
使用此功能需要启用 HTML 图片解析。
图表块必须 仅 包含两个组件；一个图片，可以是 Markdown 或 HTML 语法，以及一个用于标题的段落。请参见下面的示例。
与提示一样，图表可以设置额外的类。 警告的“标题”用作可由交叉引用定位的标签。
例如，代码
:::{figure-md} markdown-fig
<img src="../images/fun-fish.png" alt="fishy" class="bg-primary mb-1" width="200px">
这是一个用 **Markdown** 编写的标题！
:::
生成以下图片：
Fig. 3 这是一个用 Markdown 编写的标题！#
正如我们在这里看到的，我们可以引用该图片：
我们只需使用警告的标题作为目标：
[去看看鱼！](markdown-fig)
引用图片#
然后你可以通过使用 {ref} 角色或 Markdown 风格的引用方式来引用你的图片，例如：
- {ref}`directive-fig`
- [](markdown-fig)
这将用图片标题替换引用，如下所示：
编号引用#
另一种创建交叉引用的便捷方式是使用 {numref} 角色，它通过对象自动获得的编号来引用它们。例如，{numref}`directive-fig` 将产生如下引用：Fig. 2。
如果提供了明确的文本，此标题将作为引用的标题。例如，
- {ref}`飞向机器人 <directive-fig>`
- [游向鱼](markdown-fig)
产生以下交叉引用：
使用 numref，你还可以单独访问图片编号和标题：序列 “%s” 和 “{number}” 将被替换为图片编号，而 “{name}” 将被替换为图片标题。
例如，{numref}`图 {number}: {name} <directive-fig>` 将产生 图 2: 这是我的图表标题！。
图片或表格列表#
如果你正在撰写如论文或书籍等大型文档，创建 LaTeX 构建输出中的 图片列表 或“表格列表”索引可能会有用。目前默认情况下无法实现这一点，因为图片/表格标题中不支持“短标题”。不过，可以参考 此 GitHub 评论 了解解决方法。
边距标题和图片#
你可以使用 :figclass: margin-caption 在边距中包含图片标题，如 Fig. 4 所示：
Fig. 4 这是我的图片标题！#
另一种选择是使用 :figclass: margin 在边距中包含图片，如 Fig. 5 所示：
Fig. 5 这是我的图片标题！#
图片缩放和对齐#
图片也可以通过使用选项 :align: right 或 :align: left 来对齐。默认情况下，图片居中对齐（见 Fig. 2）。
要将图片左对齐，你可以写
```{figure} ../images/cool.jpg
---
scale: 50%
align: left
---
这是我的图片标题！
```
得到
Fig. 6 这是我的图片标题！#
同样，如果你写
```{figure} ../images/cool.jpg
---
scale: 50%
align: right
---
这是我的图片标题！
```
你的图片将右对齐：
Fig. 7 这是我的图片标题！#
图片参数#
支持以下选项：
scale: 整数百分比均匀缩放图片。默认值为“100”，表示无缩放。符号“%”是可选的。
width: 长度或百分比你可以用以下单位设置图片宽度：“em”、“ex”、“px”、“in”、“cm”、“mm”、“pt”、“pc”、“%”。
height: 长度你可以用以下单位设置图片高度：“em”、“ex”、“px”、“in”、“cm”、“mm”、“pt”、“pc”。
alt: 文本如果图片无法显示或读者使用辅助技术时显示的文本。通常包含图片的简短描述。
align: “left”, “center”, 或 “right”将图片左对齐、居中或右对齐。默认对齐方式为居中。
name: 文本图片的唯一标识符，你可以使用
{ref}或{numref}角色引用它。不能包含空格或特殊字符。figclass: 文本图片的类属性值，可用于添加自定义 CSS 或 JavaScript。预定义选项包括：
“margin” : 在边距中显示图片
“margin-caption” : 在边距中显示图片标题