Navigation behaviors

Darwin Information Typing Architecture (DITA) Version 1.2

DITA includes markup that processors may use to generate reader navigation to or across DITA topics.

While DITA content can be processed to create output with media-specific navigational aids, this topic discusses only the behaviors that are derived from markup.

Tables of contents (TOCs)

Processors may generate a TOC based on the hierarchy of the <topicref> elements in the DITA map. Each <topicref> element in the map represents a node in the TOC (unless it is set as a "resource only" topic reference). These topic references define a navigation tree. When a map contains a topic reference to a map (often called a map reference), processors should integrate the referenced map's navigation tree with the referencing map's navigation tree at the point of reference. In this way, a deliverable may be compiled from multiple DITA maps.

Note:

If a <topicref> element that references a map contains child <topicref> elements, the processing behavior of the child <topicref> elements is undefined.

By default, the text for each node in the TOC is obtained from the referenced topic's title. If the @locktitle attribute on the <topicref> element is set to "yes", the node text must be taken from the @navtitle attribute or <navtitle> child element of the <topicref> element and must not be read from the referenced topic's title. If a <topicref> element contains both a <navtitle> child element and a @navtitle attribute, the @locktitle attribute applies to both <navtitle> and @navtitle and, when set to "yes", the value of the <navtitle> element must be used.

A TOC node is generated for every <topicref> element (or specialization thereof) that references a topic or specifies a navigation title, except in the following cases:

  • The @processing-role attribute is specified on the <topicref> element or an ancestor element.
  • The @print attribute is specified on the <topicref> element or an ancestor element and the current processing is not for print output.
  • Conditional processing is used to filter out this node or an ancestor node.
  • No @href or @navtitle attribute is set and no child <navtitle> element exists, or the node is a <topicgroup> element.

To suppress a <topicref> element from appearing in the TOC, set its @toc attribute to "no". The value of the @toc attribute cascades to child <topicref> elements, so if @toc is set to "no" on a particular <topicref>, all of that <topicref>'s children are also excluded from the TOC. If a child <topicref> overrides the cascading TOC node suppression by specifying @toc="yes", then the node that specifies @toc="yes" must appear in the TOC (minus the intermediate nodes that turned off @toc).

Indexing

An index may be generated from index entries occurring in topic bodies, topic prologs, or DITA maps. For more information, see the language reference for the <indexterm> element.