Topic elements

Use the generic topic structure for untyped topics. While much of the DITA architecture is built upon generic topics, it is generally better to use more specific information types (such as concept, task, or reference) when they are available. For an answer to the question "What are topics?" and more details on when to use different information types, please refer to the DITA architectural specification.

  1. topic
    The <topic> element is the top-level DITA element for a single-subject topic or article. Other top-level DITA elements that are more content-specific are <concept>, <task>, <reference>, and <glossary>.
  2. title
    The <title> element contains a heading or label for the main parts of a topic, including the topic as a whole, its sections and examples, and its labelled content, such as figures and tables. Beginning with DITA 1.1, the element may also be used to provide a title for a map.
  3. titlealts
    The alternate title element (<titlealts>) is optional, but can occur after the topic title. Two elements can be inserted as sub-elements of <titlealts>: navigation title <navtitle> and search title <searchtitle>.
  4. navtitle
    The navigation title (<navtitle>) element is one of a set of alternate titles that can be included inside the <titlealts> element. This navigation title may differ from the first level heading that shows in the main browser window. Use <navtitle> when the actual title of the topic isn't appropriate for use in navigation panes or online contents (for example, because the actual title is too long).
  5. searchtitle
    When your DITA topic is transformed to XHTML, the <searchtitle> element is used to create a title element at the top of the resulting HTML file. This title is normally used in search result summaries by some search engines, such as that in Eclipse (http://eclipse.org); if not set, the XHTML's title element defaults to the source topic's title content (which may not be as well optimized for search summaries)
  6. abstract
    The abstract element occurs between the topic title and the topic body, as the initial content of a topic. It can contain paragraph-level content as well as one or more shortdesc elements which can be used for providing link previews or summaries. The <abstract> element cannot be overridden by maps, but its contained <shortdesc> elements can be, for the purpose of creating link summaries or previews.
  7. shortdesc
    The short description (<shortdesc>) element occurs between the topic title and the topic body, as the initial paragraph-like content of a topic, or it can be embedded in an abstract element. The short description, which represents the purpose or theme of the topic, is also intended to be used as a link preview and for searching. When used within a DITA map, the short description of the <topicref> can be used to override the short description in the topic.
  8. body
    The <body> element is the container for the main content of a <topic>.
  9. section
    The <section> element represents an organizational division in a topic. Sections are used to organize subsets of information that are directly related to the topic. For example, the titles Reference Syntax, Example and Properties might represent section-level discourse within a topic about a command-line process—the content in each section relates uniquely to the subject of that topic. Multiple sections within a single topic do not represent a hierarchy, but rather peer divisions of that topic. Sections cannot be nested. A section may have an optional title.
  10. example
    The <example> element is a section with the specific role of containing examples that illustrate or support the current topic. The <example> element has the same content model as <section>.
  11. related-links
    The related information links of a topic (<related-links> element) are stored in a special section following the body of the topic. After a topic is processed into it final output form, the related links are usually displayed at the end of the topic, although some Web-based help systems might display them in a separate navigation frame.
Previous topic: Introduction
Next topic: Concept elements

Return to main page.

OASIS DITA Language Specification v1.1 -- Committee Draft 13 February 2007
Copyright © OASIS Open 2005, 2007. All Rights Reserved.