Glossary · Maps and linking

DITA topic reference

Also known as: topicref, topic reference

In DITA, a topic reference (<topicref>) is the basic map element: it references a topic, map or other resource and places it in the map hierarchy. Topic references can nest, carry metadata that applies to the referenced resource and define keys.

DITA
Maps and linking

In one sentence

A DITA topic reference (<topicref>) places a topic or other resource in a map, defines its position in the hierarchy and can define keys.

Example

The topic reference <topicref href="replace-filter.dita"/> nested inside the reference to the filter concept makes the task a child of that concept in the navigation.

How it applies

Technical documentation: Nesting topic references builds the navigation hierarchy: a topicref inside another becomes a child topic, which output formats turn into subchapters, nested help entries or breadcrumbs.
Attributes: Topicrefs point to their target with @href or @keyref, can define keys with @keys, set @scope (local, peer, external), @format and @processing-role (whether the target appears in navigation), control linking with @collection-type and @linking, and change the output unit with @chunk.
Metadata: A topicref can carry <topicmeta> and conditional processing attributes. Metadata set on a topicref applies to the topic in this map only, so the same topic can have different metadata in different deliverables.

Topic reference vs. content reference

A topic reference places a whole topic into a map. A content reference pulls an element's content into another topic or map.

In DITA markup

<topicref href="filter-basics.dita" collection-type="sequence">
  <topicref keyref="replace-filter"/>
  <topicref href="filter-specs.dita" toc="no"/>
</topicref>