<shortdesc>

A short description is a sentence or group of sentences that describes the purpose or main point of the topic.

Usage information

When present in topics, the short description is the first paragraph of the topic. It can also be used for hover text, link previews, search results, and more.

When present in maps, the <shortdesc> element is associated with <topicref> elements. This enables map authors to accomplish the following goals:

  • Associate a short description with a non-DITA object
  • Provide a short description that is specific to the map context and used for link previews

When a <shortdesc> element applies to an entire DITA map, it serves only as a description. DITA architects might use such a <shortdesc> element to store information about the purpose of the DITA map.

Rendering expectations

Processors SHOULD render the content of the <shortdesc> element as the initial paragraph of the topic.

When processors generate link previews that are based on the map context, they SHOULD use the content of the <shortdesc> that is located in the map rather than the <shortdesc> that is located in the DITA topic. However, when processors render the topic itself, they SHOULD use the content of the <shortdesc> element that is located in the DITA topic.

Processing expectations

When a <shortdesc> element occurs in a DITA map, it overrides the short description provided in the topic for the purpose of generating map-based link previews. It does not replace the <shortdesc> in the rendered topic itself. This means that generated map-based links to this topic will use the short description from the map for any link previews provided with the link, while the rendered topic continues to use the short description located in the topic.

Attributes

The following attributes are available on this element: universal attributes.

Examples

This section contains examples of how the <shortdesc> element can be used.

Figure 1. Short description in a topic

The following code sample shows how a <shortdesc> element can be used in a topic:

<topic id="intro-to-bird-calling">
  <title>Introduction to bird calling</title>
  <shortdesc>If you want to attract more birds to your Acme Bird Feeder, learn the art of 
      bird calling. Bird calling is an efficient way to alert more birds to the presence of 
      your bird feeder.
  </shortdesc>
 <body>
   <!-- ... -->
 </body>
</topic>
Figure 2. Short description in a map

The following code sample shows how a short description can be used in a DITA map to provide information about a non-DITA resource. The content of the <shortdesc> element is used when a link preview to the Web site for the American Birding Association is generated.

<map>
  <title>Enjoying birds</title>
    <topicref href="birds-in-colorado.dita"/>
    <topicref href="bird-calling.dita"/>
    <topicref href="https://www.birding.example.com/" format="external" type="html">
      <topicmeta>
        <shortdesc>The American Birding Association is the only organization 
            in North America that specifically caters to recreational birders.
            Its mission is to "inspire all people to enjoy and protect wild birds."
        </shortdesc>
      </topicmeta>
    </topicref>
</map>