Linking in DITA

Linking Between Parent, Child, and Sibling Topics

A DITA map creates a hierarchical relationship between topics. That relationship map expresses a narrative flow from one topic to another, or it may be used as a classification system to help the reader find topics based on their classification, without creating a narrative flow. Since there may be various types of relationships between topics in a hierarchy, you may want to create links between topics in a variety of ways. For instance, if your topics are supposed to be organized into a narrative flow, you may want to have links to the next and previous topics in that flow. If your topics are part of a hierarchical classification, you may want links from parent to child topics, and vice versa, but not to the next and previous topics.

Parent, child, and sibling links are created automatically by the DITA output transformations (and may differ between various output formats). The kinds of links that are created are determined by the DITA collection-type attribute.

In-Line Linking in the Content of a Topic

DITA supports linking within the text of a topic using the <xref> element. The destination of the link can be expressed directly using the @href attribute or indirectly using the @keyref attribute. If you use the @keyref attribute, you link to a key rather than directly to a topic. That key is then assigned to a topic in a map that includes that topic. This means that you can change the destination that a key points to by editing the key definition in the map or by substituting another map in the build.

Linking Between Related Topics

In addition to the relationships between topics that expressed by their place in the hierarchy of a map, a topic may be related to other topics in various ways. For instance, a task topic may be related to a concept topic that gives the background of the task, or to a reference topic that provides data needed to complete the task. Task topics may also be related to other tasks in a related area, or concepts to related concepts.

Typically, they are grouped in a list at the end of the topic, although this depends on the behavior of the output transformation. DITA provides two mechanisms for expressing relationships between topics at the topic level: the Related Links section of a topic and relationship tables in maps. To add related links, select Related Link to Topic, Related Link to File, or Related Link to Web Page from the Link drop-down menu from the toolbar (or the Link submenu in the contextual menu or DITA menu).

Managing Links

Links can break for a variety of reasons. The topic that a link points to may be renamed or removed. A topic may be used in a map that does not include a linked topic. A topic or a key may not exist in a map when a particular profile is applied. The DITA Maps Manager provides a way to validate all the links in the documents that are included in the map. This can include validating all the profiling conditions that are applied.