Images and figures
MyST Markdown can be used to include images and figures in your documents as well as referencing those images easily throughout your website, article or paper.
Simple imagesΒΆ
The simplest way to create an image is to use the standard Markdown syntax:

You can explore a demo of images in the discussion of CommonMark features of MyST.
Using standard markdow to create an image will render across all output formats (HTML, TeX, Word, PDF, etc). However, this markdown syntax is limited in the configuration that can be applied beyond alt
text and an optional title
. For example, the image width, alignment or a figure caption cannot be set with this syntax.
There are two directives that can be used to add additional information about the layout and metadata associated with an image.
- image
- The
image
directive allows you to customize width, alignment, and other classes to add to the image - figure
- The
figure
directive can contain a figure caption and allows you to cross-reference this in other parts of your document.
Image directiveΒΆ
```{image} https://source.unsplash.com/random/500x150?sunset :alt: Beautiful Sunset :width: 500px :align: center ```
Figure directiveΒΆ
```{figure} https://source.unsplash.com/random/400x200?beach,ocean :name: myFigure :alt: Random image of the beach or ocean! :align: center Relaxing at the beach π π π ```
Supported Image FormatsΒΆ
MyST supports many images formats including .png
, .jpg
, .gif
, .tiff
, .svg
, .pdf
, and .eps
.
Many of these image formats are easily supported for HTML themes including .png
, .jpg
and .gif
. However, the raster image formats can be further optimized to improve site performance, MyST translates these to the modern .webp
format while the site is building. The original file-format is also included your site, with a srcset
and fallback for older web-browsers.

.png
is natively supported in all exports. The image is converted to .webp
for web-browsers.

.jpg
or .jpeg
is natively supported in all exports. The image is converted to .webp
for web-browsers.

.gif
is supported web-browsers and Microsoft Word, the first frame is extracted for and PDF exports. The image is converted to .webp
for web-browsers.

.tiff
is not supported by most web-browsers, and is converted to .png
. Microsoft Word, and PDF exports can work with these .png
images, which are also converted to .webp
for web-browsers.
.svg
is supported by web-browsers and is not further optimized or rasterized. When exporting to and PDF the images are translated to .pdf
using inkscape
or as a fallback to .png
using imagemagick
. Microsoft Word requires the .png
export.

A .pdf
image is not supported by web-browsers or Microsoft Word. The images are translated to .png
using imagemagick
. and PDF use the .pdf
image directly.

An .eps
image is not supported by web-browsers or Microsoft Word. The images are translated to .png
using imagemagick
. and PDF use the .eps
image directly.
Image TranslationsΒΆ
There are formats that are not supported by web-browsers but are common in scientific writing like .tiff
, .pdf
and .eps
for site builds, these are converted to .svg
or .png
as appropriate and available. For export to , PDF or Microsoft Word, the files are converted to an appropriate format that the export can handle (e.g. can work directly with .pdf
images). For animated images, .gif
, the first frame is extracted for static exports.
Installing Image Converters
The image translations and optimizations requires you to have the following packages installed:
- imagemagik for conversion between raster formats
- inkscape for conversion between some vector formats
- webp for image optimizations
Multiple ImagesΒΆ
If you have manually converted your images or have different images for different formats, use an asterisk (*
) as the extension. All images matching the provided pattern will be found and the best image out of the available candidates will be used for the export:

For example, when exporting to the best format is a .pdf
if it is available; in a web export, a .webp
or .svg
will be chosen before a .png
. In all cases, if an appropriate format is not available the image will be translated.