Images and Videos

Use the media element to add any type of media to your document, including images. Specify that the media is an image by setting the type attribute to "image". Use the src attribute to provide the URL for the image. Try this example by adding it as a block element to a Mallard document; that is, add it where you would normally add a paragraph.

<media type="image" src="mallard-logo.png"/>

You can also provide the size of the image with the width and height attributes. You can use these attributes to scale the image to different dimensions. The attribute values are numbers without any units; they are always interpreted as pixels.

<media type="image" src="mallard-logo.png" width="240" height="60"/>

When you use the media element in a block context, it is treated as a block element. But you can also use the media element inline to add images in running text, such as inside a paragraph.

<p>Powered by <media type="image" src="mallard-badge.png"/></p>

You can add a video to your document in the same way you added an image. Simply set the type attribute to "video" and point the src attribute to the URL of your video.

<media type="video" src="mallard-logo.webm"/>

Mallard is a source format. It is designed to be easy to convert to other formats that may be more suitable for particular needs. Some types of media are not possible in some target formats. For example, a printed document can't show a video. A UNIX manual page can't show an image. Even in a media-rich online environment, alternative text content is helpful to blind users using a screen reader.

Mallard allows you to specify fallback content by adding content inside the media element. What you can add depends on where you use the media element. If you use it as a block element, you can add any block elements inside it, such as paragraphs or code blocks.

<media type="image" src="mallard-logo.png">
  <p>The Mallard logo: a question-mark-shaped duck head in a circle</p>
</media>

If you use the media element as an inline element, you can use text and any inline elements as fallback content.

<p>Powered by <media type="image" src="mallard-badge.png">Mallard</media></p>

You can even use other media elements inside the fallback content. The fallback media elements can also have fallback content.

<media type="video" src="mallard-logo.ogv">
  <media type="image" src="mallard-logo.png">
    <p>The Mallard logo: a question-mark-shaped duck head in a circle</p>
  </media>
</media>

If you view this in a text-only environment, you will only see the text fallback content.

Images are often accompanied by titles or captions. Titles and captions can help readers understand the image and refer to it later. This is especially important for diagrams and charts, where you may need to explain what certain notations mean. You can add a title or a caption using the figure element.

<figure>
  <title>Mallard Logo</title>
  <desc>The Mallard logo is a question-mark-shaped duck head in a circle.</desc>
  <media type="image" src="mallard-logo.png"/>
</figure>

Mallard Logo

The Mallard logo is a question-mark-shaped duck head in a circle.

The title element provides a title for the figure, while the desc element provides a caption. Both elements are optional, although you should use at least one of them. Note that both title and desc take normal inline content, not paragraphs or other block content. When you use a media element inside a figure element, it is interpreted as a block element. So any fallback content must also be block content.

<figure>
  <title>Mallard Logo</title>
  <desc>The Mallard logo is a question-mark-shaped duck head in a circle.</desc>
  <media type="image" src="mallard-logo.png">
    <p>The Mallard logo: a question-mark-shaped duck head in a circle</p>
  </media>
</figure>

In this tutorial, you learned how to add images and videos with fallback content, titles, and captions. To learn more about media and figures, read the specification pages and examples on block media, inline media, and figures.