Figures¶

MyST Markdown also lets you include figures in your page. Figures are like images, except that they are easier to reference elsewhere in your book, and they include things like captions. To include a figure, use this pattern:

```{figure} ../images/C-3PO_droid.png
---
height: 150px
name: my-figure
---
Here is my figure caption!
```

Fig. 1 Here is my figure caption!¶

Note

You can also include figures that were generated from your code in notebooks. To do so, see Insert code outputs into page content.

Referencing figures¶

You can then refer to this figure using the {ref} role like: {ref}`my-figure`, which will replace the reference with the figure caption like so: Here is my figure caption!. Another convenient way to create cross-references is with the {numref} role, which automatically numbers the labelled objects. For example, {numref}`my-figure` will produce a reference like: Fig. 1.

If an explicit text is provided, this caption will serve as the title of the reference. The characters “%s” and “{number}” will be replaced with a figure number, while “{name}” will be replaced with a figure caption. For example, {numref}`Figure {number}: {name} <my-figure>` will produce: Figure 1: Here is my figure caption!.

Margin captions and figures¶

You can include a figure caption on the margin using :figclass: margin-caption as seen in Fig. 2.

Fig. 2 Here is my figure caption!¶

Another option is to include figures on the margin using :figclass: margin as seen in Fig. 3.

Fig. 3 Here is my figure caption!¶

Figure scaling and alignment¶

Figures can also be aligned by using the option :align: right or :align: left. By default, figures are aligned to the center (see Fig. 1).

```{figure} ../images/cool.jpg
---
scale: 50%
align: left
---
Here is my figure caption!
```

Fig. 4 Here is my figure caption!¶

```{figure} ../images/cool.jpg
---
scale: 50%
align: right
---
Here is my figure caption!
```

Fig. 5 Here is my figure caption!¶

Figure Parameters¶

The following options are supported:

scale : integer percentage

Uniformly scale the figure. The default is “100” which indicates no scaling. The symbol “%” is optional.
width : length or percentage

You can set the figure width in the following units: “em”, “ex”, “px”,”in” ,”cm”, “mm”, “pt”, “pc”, “%”.
height : length

You can set the figure height in the following units: “em”, “ex”, “px”, “in”, “cm”, “mm”, “pt”, “pc”, “”.
alt : text

Text to be displayed if the figure cannot display, or if the reader is using assistive technologies. Generally entails a short description of the figure.
align : “left”, “center”, or “right”

Align the figure left, center, or right. Default alignment is center.
name : text

A unique identifier for your figure that you can use to reference it with {ref} or {numref}. Cannot contain spaces or special characters.
figclass : text

Value of the figure’s class attribute which can be used to add custom CSS or JavaScript. Predefined options include:
- “margin” : Display figure on the margin
- “margin-caption” : Display figure caption on the margin