Images, Figures and Videos

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 include an image is to use the standard Markdown syntax:

![alt](link 'title')

You can explore a demo of images in the discussion of CommonMark features of MyST.

Using standard markdown 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.

There are two directives that can be used to add additional information about the layout and metadata associated with an image. For example, {image.width}, {alignment.align} or a {figure caption.body}.

image

The {image} directive allows you to customize {image.width}, {alignment.align}, and other {classes.class} to add to the image.

figure

The {figure} directive can contain a {figure caption.body} and allows you to cross-reference this in other parts of your document.

Image directive¶

The {image} directive lets you include a simple image on your page. You can control the alt-text, style, etc. Here’s an example:

Figure directive¶

Figures can wrap one-or-more images. They’ll be numbered, so referencing them creates links like Figure 1.

Subfigures¶

Subfigures are created by putting one or more images in the directive body instead of as an argument. These will be numbered as Figure 1a and Figure 1b, etc. For example:

You can cross-reference either the whole figure Figure 1, or an individual subfigure Figure 1a or Figure 1b. Each subfigure is given an implicit reference that matches the figure label with a suffix of their letter. For example, let’s say you have a parent figure and give it a label my-figure, and it has two sub-figures. Each subfigure can be referred to as #my-figure-a and #my-figure-b, respectively.

If you provide a label for a specific subfigure, that label will be used instead of the implicit label.

When referring to subfigures, the {number} that is used includes the parent enumerator by default (that is: 1a rather than just a). To use the sub-enumerator only, you can use the syntax {subEnumerator} in your text link which will be replaced with the sub-enumerator (that is: a rather than 1a).

CSS classes can be applied to make subfigures appear side-by-side or in a grid layout. :class: grid grid-cols-2 items-end gap-4 can be used to create a two-column grid of images with aligned bottoms and a gap between them.

Control sub-figure layout with a grid¶

For responsive layouts, wrap the content in a {grid} directive. In this case, the figure has a single entry, representing the grid of images that you provide. It will not create implicit references for sub-figures as desecribed above. The example below uses one column on narrow screens and two on wide ones (1 1 2 2).

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

JPG

GIF

TIFF

SVG

PDF

EPS

Image Transformers¶

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 $\LaTeX$, PDF or Microsoft Word, the files are converted to an appropriate format that the export can handle (e.g. $\LaTeX$ can work directly with .pdf images). For animated images, .gif, the first frame is extracted for static exports.

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 available will be used for the export:

![](./images/myst-image.*)

For example, when exporting to $\LaTeX$ the best format is a .pdf (if 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 converted.

Videos¶

To embed a video you can either use a video platforms embed script or directly embed an mp4 video file. For example:

:::{figure} ./videos/links.mp4
An embedded video with a caption!
:::

or

![](./videos/links.mp4)

will copy the video to your static files and embed a video in your HTML output.

If you have ffmpeg installed, you may also include .mov and .avi video files, and MyST will convert them to .mp4 and include them. Videos can also be used in the image or even in simple Markdown image.

Use an image in place of a video for static exports¶

If you’d like an image to display for static exports (like PDFs), use the asterisk (*) wildcard matching described in Multiple Images.

For example, if you had the following two files:

myvideo.mp4  <-- A video of something
myvideo.png <-- A frame of the video as an image

Then you could link them both with:

![](myvideo.*)

When you build an HTML output, the video will be used, and when you build a PDF output, the image will be used.

YouTube Videos¶

If your video is on a platform like YouTube or Vimeo, you can use the {iframe} directive that takes the URL of the video.

You can find this URL when clicking share > embed on various platforms. You can also give the {iframe} directive {iframe.width}, {iframe.title} (for accessibility), and a {caption.body}.

Provide Light and Dark Mode images¶

To provide images for light and dark mode, use Tailwind CSS classes for light and dark mode.