`<topicref>`

The <topicref> element identifies a topic (such as a concept, task, or reference) or other resource. A <topicref> can contain other <topicref> elements, allowing you to express navigation or table-of-contents hierarchies, as well as implying relationships between a containing (parent) <topicref> and its children. You can set the collection type of a parent <topicref> to determine how its children are related to each other. You can also express relationships among <topicref> elements by using group and table structures (such as <topicgroup> and <reltable>). Relationships are expressed as links in the output; by default, each participant in a relationship has links to the other participants in that relationship.

You can fine tune the output from your map by setting different attributes on the <topicref> element. For example, the @linking attribute controls how a topic's relationships to other topics are expressed as links, and the @toc attribute controls whether the topic shows up in TOC or navigation output.

Content models

See appendix for information about this element in OASIS document type shells.

Inheritance

- map/topicref

Example

In this example, there are six <topicref> elements. They are nested and have a hierarchical relationship. bats.dita is the parent topic and the other topics are its children.

<map title="Bats">
 <topicref href="bats.dita" type="topic">
  <topicref href="batcaring.dita" type="task"></topicref>
  <topicref href="batfeeding.dita" type="task"></topicref>
  <topicref href="batsonar.dita" type="concept"></topicref>
  <topicref href="batguano.dita" type="reference"></topicref>
  <topicref href="bathistory.dita" type="reference"></topicref>
 </topicref>
</map>

Attributes

The following attributes are available on this element: Universal attribute group, Link relationship attribute group (with a narrowed definition of @href, given below), Attributes common to many map elements, Topicref element attributes group, outputclass, @keys, and @keyref.

@href: A pointer to the resource 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.