Unexpected DITA Publishing Output Results


When users execute a DITA-OT publish on a DITA asset collection, the system generates unexpected output file results in the CMS pub folder.

Unexpected output results may include but are not limited to the following:

  • The DITA output files do not reside in the expected DITA output file architectural structure.
  • The DITA output files contain other asset files not included in the publish.
  • The DITA output files have missing content. This can include missing asset files or missing content within asset files.
  • The views associated with the DITA output do not display the content correctly.
  • The JSON associated with the DITA output did not process correctly.

Troubleshooting Unexpected DITA Publishing Results
Troubleshooting Unexpected DITA Publishing Results


A spectrum of issues can cause the DITA-OT transformation to generate unexpected output file results. These issues can vary depending on factors involved. Keep in mind that these steps provide general guidelines and direction for pinpointing and resolving a wide range of issues that may cause the unexpected output generation.

Output Issue Diagnosis

System administrators and users.
Identify the issue that causes the unexpected output generation.

To diagnose the issue:

  1. Double-check your DITA publishing setup. Also, if applicable, double-check your views setup and JSON processor setup.
    Ensure the appropriate settings were in place when the system executed the DITA publish.

    See the DITA Publishing Pipeline Troubleshoot Checklist to double check your DITA administration settings and DITA publishing settings.

  2. Run debug mode to include debugging details in the next DITA publish log.

    See Running DITA Debug Mode for details.

  3. Apply the same DITA publishing settings used when you encountered the unexpected output, and run the DITA publish process again. Check the DITA log for errors.

    These errors may provide details about where the conflict resides and what the conflict entails.

  4. Check the CMS publishing log for errors and to review the output files generated during the DITA publish post processing.
  5. Check the DITA output directory to review the output files within the CMS site directory.
    See Checking DITA Publishing Output Directory for details.
    If the DITA logs indicate the DITA-OT transformation process failed in the Has Errors column, then skip this step.
  6. Review the DITA temp folder for discrepancies within the temporary files that may relate to the issue.
  7. If you discover errors within the logs, decipher them to determine what the conflicts entail.

Address Output Issues

System administrators and users.

Use the information you gathered from troubleshooting to resolve output issues.

The following list provides potential solutions to address your issue. Keep in mind that you may uncover alternative solutions not provided in this list.

After implementing your solution, republish the DITA asset collection, and then review the DITA logs and output files to see if the output files generate as expected. If you still encounter issues, try another solution or contact Ingeniux Support.