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: revised (2019-11-17)
Target: 1.2
show history
hide history
2014-02-04 ui/1.0 proposed
2019-11-17 1.2 revised Move thumb to Mallard core and use MEP-0018

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. It even allows for multiple titles for different purposes, and pending MEP-0008, it will allow multiple descriptions 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 thumb elements in any info element. The 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.

There is a proposal to remove the mime attribute from media. Perhaps the thumb element shouldn't reintroduce it.


A type, similar to the type on informational titles, that may be used to select the most appropriate thumbnail. This is notably not the same use as the type on a media element.


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

The type and role attributes work similarly to the same attribute on link titles. Looking up the correct thumbnail would follow the new lookup rules defined in MEP-0018: Type-and-Role Data.

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.

In addition to using thumbs for pages and sections, a thumb element for a video-type media element should be used as a poster image for the video, instead of the current non-standard convention of using a child media element with the style attribute set to "poster".


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

<page xmlns=""
    <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>
    <thumb src="network-panel-big.png" role="topic" width="300" height="200"/>
    <title type="link" role="gallery">Network</title>
    <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">
    <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.

The original version of this proposal placed the thumb element in the ui namespace from Mallard UI. Though there are many uses for thumbnails in UI extensions, there are also uses for it in other potential extensions or in core Mallard features. Consequently, we decided to put the thumb element in 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-2019 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