References Outside the Main DITA Map Folder

Problem

A reference to a DITA topic, map, or binary resource (for example, an image) that is located outside of the folder where the main DITA map is located leads to problems when publishing the content using the DITA Open Toolkit.

Cause

DITA-OT often has trouble resolving references that are outside the directory where the published DITA map is found. By default, it does not even copy the referenced topics to the output directory.

Solution

To solve this, try one of the following solutions:

Create another DITA map that is located in a folder path above all referenced folders and reference the original DITA map from this new map. Then transform this DITA map instead.
Edit the transformation scenario and in the Parameters tab, change the value of the fix.external.refs.com.oxygenxml parameter to true. This parameter is used to specify whether or not the application tries to fix such references in a temporary files folder before the DITA Open Toolkit is invoked on the fixed references. The fix has no impact on your edited DITA content.
Important: The fix.external.refs.com.oxygenxml parameter is only supported when the DITA-OT transformation process is started from Oxygen XML Author Eclipse plugin or using the transform script.
For PDF output, you can edit the transformation scenario and in the Parameters tab set the value of the generate.copy.outer parameter to 3. This parameter specifies whether to generate output files for content that is not located in or beneath the directory containing the DITA map file. By setting the value of this parameter to 3, the transformation scenario shifts the output directory so that it contains all output for the publication.
Important: This method is recommended for transformation scenarios that use an external DITA-OT.