Images and Videos

Learn by Example

This page was written in a Mallard extension format called Mallard Sites. Read the source markup for this page to learn Mallard from real-world examples.

A picture tells a thousand words, but only if those words describe that picture. Documentation often uses screenshots to highlight relevant parts of an interface, or diagrams and charts to better illustrate some information. Furthermore, screencast videos are increasingly more common, because they show user actions and program activity directly.

In this tutorial, you will learn how to insert images and videos into your Mallard document. You will also learn how to create figures with titles and captions.

Images

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>

Powered by

Videos

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.ogv"/>
0:00-:--

When Mallard documents are converted to HTML, support for videos depends on browser support for the HTML video tag.

Fallback Content

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>

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

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>

Powered by Mallard

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>
The Mallard logo: a question-mark-shaped duck head in a circle

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

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

Figures

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>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>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>

Mallard Logo

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

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

Learn More

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.