Topic reference

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.

Syntax

The syntax for representing this component varies depending on the authoring format:

Authoring format Syntax and example
XDITA

<topicref>

<topicref href="alternatives.dita">
  <topicref href="low-power.dita"/>
  <topicref href="high-power.dita"/>
</topicref>
HDITA

<a href> inside of a list item

<li><a href="alternatives.html">Alternative lighting setups</a>
  <ul>
    <li><a href="low-power.html">Low power installation</a></li>
    <li><a href="high-power.html">High power installation</a></li>
  </ul>
</li>
MDITA

[link text](URI) inside of a list item

- [Alternative lighting setups](alternatives.md)
 - [Low power installation](low-power.md)
 - [High power installation](high-power.md)

Attributes

The available attributes vary based on the authoring format:

XDITA and HDITA
The following attributes are available on this element: ID attributes, link relationship attributes, localization attributes, universal attributes, @keys, @keyref, and @props.
MDITA
For the MDITA core profile, the equivalent of the XDITA @keyref attribute is supported. For the MDITA extended profile, attributes can be specified by using the HDITA representation.

Examples

This section contains examples of how the topic reference component can be used.

Figure 1. XDITA example

The following code sample shows a simple DITA map that represents the Acme Widget User Guide. Each of the <topicref> elements represents the top-level topic for a chapter, and indirect addressing is used to reference the DITA topics.

map>
  <topicmeta>
    <navtitle>Acme Widget User Guide</navtitle>
  </topicmeta>
  <keydef href="key-definitions.ditamap"/>
  <topicref keyref="installing">
    <!-- … -->
  </topicref>
  <topicref keyref="configuring">
    <!-- … -->
  </topicref>
  <topicref keyref="administering">
    <!-- … -->
  </topicref>
  <topicref keyref="developing">
    <!-- … -->
  </topicref>
  <topicref keyref="troubleshooting">
    <!-- … -->
  </topicref>
</map>
Figure 2. HDITA example

The following code sample shows a simple DITA map that represents the Acme Widget User Guide. Each of the topic reference components represents the top-level topic for a chapter, and direct addressing is used to reference the HDITA topics.

<ul>
  <li><a href="installing.html">Installing Acme Widget</a>
      <! ... -->
  </li>
  <li><a href="configuring.html">Configuring Acme Widget</a>
      <! ... -->
  </li>
  <li><a href="administering.html">Administering Acme Widget</a>
      <! ... -->
  </li>
  <li><a href="developing.html">Developing Acme Widget applications</a>
      <! ... -->
  </li>
  <li><a href="troubleshooting.html">Troubleshooting Acme Widget</a>
      <! ... -->
  </li>
</ul>
Figure 3. MDITA example

The following code sample shows a simple DITA map that represents the Acme Widget User Guide. Each of the topic reference components represents the top-level topic for a chapter, and direct addressing is used to reference the MDITA topics.

- [Installing Acme Widget](installing.md)
 <!-- ... -->
- [Configuring Acme Widget](configuring.md)
 <!-- ... -->
- [Administering Acme Widget] (configuring.md)
 <!-- ... -->
- [Developing Acme Widget apps (developing.md)
 <!-- ... -->
- [Troubleshooting Acme Widget (troubleshooting.md)