Images & Figures¶

Embedding and formatting visual content in your documentation.

Basic Images¶

Use standard Markdown syntax to embed an image.

The MyST syntax:

![Alt text](path/to/image.png)

Tip

Always include descriptive alt text. It improves accessibility for screen reader users and appears as fallback text if the image fails to load.

Image Directive¶

The image directive gives you control over width, alignment, and alt text that Markdown syntax doesn’t offer.

The MyST syntax:

```{image} path/to/image.svg
:alt: Description of the image
:width: 200px
:align: center
```

Alignment Options¶

Images can be aligned left, center, or right within the content area.

Left — text wraps around the right side.

Center — image stands alone.

Right — text wraps around the left side.

Figures¶

Figures wrap an image with a caption and optional legend. Use them when an image needs explanation or attribution.

Figure 1. A wide placeholder image demonstrating the figure directive. Figures support full Markdown in captions including bold, italic, and code.¶

The MyST syntax:

```{figure} path/to/image.svg
:alt: Description
:width: 100%
:align: center

Caption text with **Markdown** support.
```

Tip

Use figures instead of bare images when you need a caption. Figures are also the correct semantic choice for diagrams, screenshots, and charts — anything that the text refers to by number or name.

Scaled Images¶

Control image size as a percentage of the content width.

100% width

50% width

25% width

You can use percentages, pixels, or any CSS length unit:

:width: 50%       # Percentage of content width
:width: 300px     # Fixed pixel width
:width: 20em      # Relative to font size

Linked Images¶

Wrap an image in a link to make it clickable.

The MyST syntax:

[![Alt text](thumbnail.png)](full-size.png)

Images in Admonitions¶

Images work inside any block element, including admonitions and cards.

Note

Images inside admonitions maintain their styling. This is useful for annotated screenshots or diagrams that accompany a specific instruction.

File Format Guidance¶

Choose the right format for your images:

Format	Best for	Notes
SVG	Diagrams, icons, logos	Scales to any size without quality loss. Smallest file size for simple graphics. Preferred for anything that isn’t a photograph.
PNG	Screenshots, UI captures	Lossless compression. Good for images with text, sharp edges, or transparency.
WebP	Photos, complex images	Modern format with excellent compression. Supported by all current browsers.
JPEG	Photos (fallback)	Wide compatibility. Use WebP instead when possible for smaller files.

Tip

Store images in a _images/ subdirectory within your docs folder to keep things organized. Reference them with relative paths: _images/my-screenshot.png.