Topics within a DITA map can be linked to external resources, allowing authors to reference content located outside the DITA map structure. This enables the incorporation of content from external documents, websites, or other sources into the DITA documentation.

Integrating External Content

DITA maps offer the capability to link topics to external resources, providing flexibility in integrating content from sources outside the DITA project. This is particularly useful when authors want to reference content from external documents, websites, or other resources within the structured DITA documentation.

Tools available to authors for this purpose include <topicref> elements, using the attributes href, format, and scope.

Using <topicref> Elements

In a DITA map, topics are typically organized using <topicref> elements. These elements reference DITA topics and determine the order in which the topics appear within the map. While most <topicref> elements reference topics from within the DITA project, they can also reference external resources, such as documents, websites, or other content.

Attributes for Linking External Resources

Tools available to authors for this purpose include <topicref> elements, using the attributes href, format, and scope.

<topicref> Elements

In a DITA map, topics are typically organized using <topicref> elements. These elements reference DITA topics and determine the order in which the topics appear within the map. While most <topicref> elements reference topics from within the DITA project, they can also reference external resources, such as documents, websites, or other content.

href Attribute for External Links

To link to an external resource, the href attribute within a <topicref> element is used. This attribute specifies the location or URL of the external content. It can point to a file on the local file system or a remote web address. For example, if an organization has a PDF user guide hosted on their website, the href attribute can reference the URL of the PDF file.

format Attribute for File Format

The format attribute, also within the <topicref> element, specifies the file format of the linked resource. This is particularly important for DITA processing engines to understand the type of content being linked. For example, the format attribute can be set to “pdf” to indicate that the linked resource is in PDF format. This helps the rendering engine apply appropriate handling for the linked content.

scope Attribute for External Content

The scope attribute is used to indicate that the linked content is located outside the DITA map’s immediate structure and is considered an external resource. It helps distinguish between topics within the DITA project and external resources. When the scope attribute is set to “external,” it signals that the content should be retrieved from an external location.

Example

An organization creates a DITA map for its user manual. This manual includes a reference to an existing PDF user guide.

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <title>Product Documentation</title>
  <topicref href="introduction.dita" />
  <topicref href="installation.dita" />
  <topicref href="https://www.example.com/user-guide.pdf" format="pdf" scope="external" />
  <topicref href="troubleshooting.dita" />
</map>
    

In this example:

• The <map> element defines a DITA map titled “Product Documentation.”
• The map includes <topicref> elements that reference topics, such as “introduction.dita” and “troubleshooting.dita,” from within the DITA project.
• One of the <topicref> elements references an external resource via a URL (https://www.example.com/user-guide.pdf) using the href attribute. The format attribute is set to “pdf” to indicate the file format of the linked resource. The scope attribute is set to “external” to specify that the content is located outside the DITA map’s immediate structure. This allows the map to include content from an external PDF document, enhancing the documentation with information from an external source.