`<topicref>`

A topic reference is the mechanism for referencing a topic (or another resource) from a DITA map. It can nest, which enables the expression of navigation and table-of-content hierarchies, as well as containment hierarchies and parent-child relationships.

Attributes

The following attributes are available on this element: common map attributes, link-relationship attributes, universal attributes, @impose-role, @keyref, and @keys.

For this element, the @href attribute references the resource that is represented by the <topicref>. See The href attribute for detailed information on supported values and processing implications. References to DITA content cannot be below the topic level: that is, you cannot reference individual elements inside a topic. References to content other than DITA topics should use the @format attribute to identify the kind of resource being referenced.

Example

The following code sample shows a simple map that organizes several topics about the software product "Example Tool Builder". The <topicref> that refers to setup.dita uses the @collection-type attribute to indicate that the order of three children topics in that section is important.

<map>
  <title>Example Tool Builder version 1.2.3</title>
  <topicref href="setup.dita" collection-type="sequence">
    <topicref href="prerequisites.dita"/>
    <topicref href="installing.dita"/>
    <topicref href="validating.dita"/>
  </topicref>
  <topicref href="everyday-use.dita">
    <!-- ... -->
  </topicref>
  <topicref href="troubleshooting.dita">
    <!-- ... -->
  </topicref>
</map>