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 is non-normative.

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

Example 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>
Example 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>
Example 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)