Images & Figures¶

Embedding and formatting visual content in your documentation.

3 min read

Tip

Click any image on this page to view it full-size in an overlay. The lightbox is opt-in — enable it site-wide with image_lightbox = "true". Once enabled, opt out per-image with the no-lightbox CSS class or the data-no-lightbox attribute. User-defined links wrapping images keep their navigation behaviour.

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.

Wrapping Text Around Images¶

Left- and right-aligned images float, so the paragraphs that follow wrap around them. Floats end at the next heading, and on narrow screens the image stacks above the text.

Lumina keeps the gutter between a floated image and the text at the same spacing as other blocks, so the column stays easy to scan. This paragraph and the next wrap around the image on the right. Put the image just before the text it illustrates, and keep it small enough that a few lines still fit beside it.

A centered image or figure stands alone, with its caption centered underneath. Use centering for diagrams that need the full attention of the reader, and floats for supporting pictures.

The MyST syntax:

```{image} path/to/image.png
:alt: Description
:width: 160px
:align: right
```

Text that wraps around the image.

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 containing block’s width.

100% of the grid item

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.