Can DITA maps include references to non-DITA content?

DITA maps can include references to non-DITA content through the use of <topicref> elements, allowing organizations to integrate a variety of content types, such as PDFs, Word documents, or HTML files, into their structured documentation.

Flexibility in Including Non-DITA Content

DITA maps offer the flexibility to include references to non-DITA content, enabling organizations to incorporate a wide range of document formats, such as PDFs, Word documents, HTML files, or multimedia elements, into their structured documentation. This is accomplished using the <topicref> element, just as with DITA topics. When referencing non-DITA content, the format attribute within the <topicref> element is used to specify the file format of the content being linked.

Additionally, the scope attribute may be set to “external” to indicate that the content is located outside the DITA map structure. This allows DITA maps to act as containers for various content types, promoting content consolidation and streamlining document management. For example, in a software user manual, a DITA map may reference a non-DITA PDF document containing regulatory compliance information, ensuring that this external content is seamlessly integrated into the documentation structure.


In this example, a DITA map includes references to non-DITA content in PDF and HTML formats:

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
  <title>Product Documentation</title>
  <topicref href="introduction.dita" />
  <topicref href="installation.dita" />
  <topicref href="external/compliance.pdf" format="pdf" scope="external" />
  <topicref href="external/user_guide.html" format="html" scope="external" />
  <topicref href="troubleshooting.dita" />

In this example:

  • The DITA map has a title, “Product Documentation.”
  • The map includes references to both DITA topics (e.g., “introduction.dita” and “installation.dita”) and non-DITA content.
  • Two non-DITA content references are made: one to a PDF document (“compliance.pdf”) and another to an HTML document (“user_guide.html”). The format attribute specifies the file format of each content type.
  • The scope attribute is set to “external” for the non-DITA content references, indicating that these files are located outside the DITA map’s immediate structure. This allows for the seamless integration of non-DITA content into the structured documentation.