Navigation behaviors

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.