Skip to article content

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:

![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, width, alignment or a figure caption.

The image directive allows you to customize width, alignment, and other classes to add to the image
The figure directive can contain a figure caption and allows you to cross-reference this in other parts of your document.

Image directiveΒΆ

Figure directiveΒΆ

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.

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

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

Installing Image Converters

The image transforms 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 LaTeX\LaTeX 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.


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

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



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

An embedded video with a caption!

These videos can also be used in the image or even in simple Markdown image.

Videos are not currently transformed

The videos are not currently converted to static images when you export to PDF or Word. If you want to help out with this feature, please get in touch!

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 width and a caption.

MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication