The thumb Element

This page outlines a new element called thumb that would be allowed inside info elements to provide a thumbnail image that may be used for the parent element. This proposal attempts to provide a generic thumb element that may be used by different extensions.

Authors: Shaun McCance
Created: 2014-02-04
Status: proposed (2014-02-04)
Target: ui/1.0
show history
hide history
2014-02-04 ui/1.0 proposed

This proposal is still under consideration. Revisions may still be made based on your input. Discuss this proposal on mallard-list.


Mallard provides title and desc elements for pages and sections, and even allows for multiple titles for different purposes. These can be used to create rich text links. For some designs and extensions, it's useful to associate an image with a page or section. For example, a page may provide a representative screenshot or an icon that indicates its contents, and this could be shown along with the topic link from a guide page.

Additionally, some extensions may display galleries of images or videos that open the media in a popup or fullscreen window. These extensions can benefit from allowing a separate thumbnail image for the media objects that is distinct from a scaled-down version of the image or a randomly selected video frame.


This page proposes allowing zero or more ui:thumb elements in any info element, where the namespace of the ui:thumb element is the Mallard UI namespace:

The ui:thumb element has no content, and it may contain the following attributes:


The URL of the media file being used as a thumbnail.


The width and height of the file referenced by the src attribute.


The MIME type of the thumbnail.


A role, similar to the role on link titles, that may be used to select the most appropriate thumbnail.

Unlike the media element, the ui:thumb element does not take a type attribute, because it is assumed that thumbnails will be images. If this is a problem in the future, a type attribute can easily be added, since it defaults to "image" anyway.

The role attribute works similarly to the role attribute on link titles. It may be used to select the most appropriate thumbnail from a list of alternatives. When thumbnails are used for links such as from a links element, the same logic used to select a link title should be used to select a thumbnail. Other uses of thumbnails may specify roles to prefer.

In some cases, it may be useful to provide alternative sizes of the same thumbnail for the same role. In additional to using the role attribute, implementations may check the width and height attribute to select a thumbnail that has the most optimal dimensions.


Use a scaled down screenshot as a thumbnail for a page.

<page xmlns=""
    <ui:thumb src="network-panel-screenshot.png" width="300" height="200"/>

Provide multiple thumbnails with roles for a page to match the roles of the link titles.

<page xmlns=""
    <title type="link" role="topic">Network Panel</title>
    <ui:thumb src="network-panel-big.png" role="topic" width="300" height="200"/>
    <title type="link" role="gallery">Network</title>
    <ui:thumb src="network-panel-small.png" role="gallery" width="150" height="100"/>

Provide a thumbnail image to be used for a video.

<media src="open-apps.webm" type="video" width="300" height="200">
    <ui:thumb src="open-apps-thumb.png" width="300" height="200"/>


This proposal provides no way to provide alternative text for thumbnails. However, the title and desc of the parent elements is available. Implementations should take care to either set alternative text from these elements or to show the thumbnails in a way that obviates the need for alternative text, such as with background images.


Thumbnails, like all media objects, may contain translatable material, such as user interface text in a screenshot. Translation tools should allow thumbnails to be translated using the same mechanism used for media elements.


Yelp contains a number of features that use thumbnails provided by similar elements in an experimental namespace. When used on media elements, those features allow a uix:caption element to be a child of the uix:thumb element. The uix:caption element, in turn, may contain a title and desc element. (The extra wrapper element is necessary for proper fallback processing.)

The title and desc provided by uix:caption are used alongside thumbnails, which open the full media object in a popup. Because this proposal depends on MEP-0002 to provide an info element in block elements, a title and desc can simply be placed in that info element instead, possibly with role attributes.

Although thumbnails will be useful for a number of Mallard UI features, they may also be useful for designs that are accomplished only with the style hint, or from other extensions. It may be better to add the thumb element to Mallard core.

Compatibility and Fallback

This proposal makes no backwards-incompatible changes. Any page written in a version prior to the implementation of this proposal will work exactly the same in a processing tool that implements this proposal.

This page adds an informational element. Unknown informational elements are ignored by non-supporting tools, so pages using this extension will be processed as well as can be expected with non-supporting tools. It's worth noting that, because this proposal depends on MEP-0002 to add info elements to block elements, the compatiblity notes of that MEP apply to the info element. Inside the info element, however, there are no compatibility issues.

Comparison to Other Formats

DocBook allows any number of mediaobject elements inside info elements, although there are no processing expectations for these. It's possible to create some special stylings that use these elements for thumbnails.

DITA does not have a mechanism for providing thumbnails, but a specialization could do so by specializing the data element in the prolog of a topic.

© 2014 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by