DITA includes a range of elements and attributes to manage references in
ditamaps, and to govern the way the references are treated during the
The topicref element
The basic building block of ditamap files is the topic reference (topicref) element.
The href attribute in a topic references
A topic reference (topicref) in a ditamap references the topic (or other resource) to be included in the output publication through the href attribute. The value of the href attribute must conform to the standard URI format.
The topichead element
The topichead element in the ditamap provides a title-only node in the hierarchy, into which normal topic references are nested. Although technically valid, this element should not be used because it results in inconsistent output.
The navref element
The navref element is a specialist element used when constructing dynamically-merged modular Help systems.
The copy-to attribute
The copy-to attribute of the topicref element is used in the unusual situation where you need to create two copies of the same topic in the output, and to link to each copy of the output topic separately. The value of the attribute is the file name of the duplicate.
The chunk attribute
The chunk attribute can control the way output files are generated during the publishing process. Most chunk attribute values apply only to composite topics, which should be avoided. The to-content value is used to generate a single output topic from multiple DITA source topics.
Non-DITA topic references
A ditamap can include references to non-DITA resources, such as PDF documents, spreadsheet files, presentation files, online tutorials, HTML files, and Internet addresses. The topicref element is used for these references, with format and scope attributes describing the type of resource.
If a ditamap includes a reference to a topic that does not exist, the publishing process will generate output with a broken link. It will not gracefully omit the reference. You should therefore take care to avoid these dangling topicref.