Unexpected DITA Preview Results


When users execute a preview on a DITA asset, the system generates unexpected preview views or XML content in the DITA Preview and XML tabs.

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

  • The DITA preview has missing content in the rendered view.
  • The DITA preview does not display the content correctly.
  • The dependency links within the DITA preview do not resolve to the appropriate target.

Troubleshooting Unexpected DITA Preview Results
Troubleshooting Unexpected DITA Preview Results


A spectrum of issues can cause the DITA-OT transformation process to generate unexpected DITA preview output results in the DITA Preview and XML tabs. 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 unexpected DITA preview output.

Error Issue Diagnosis

Administrators can double-check the DITA publishing pipeline setup and run debug mode. Users with asset editing permissions can execute DITA preview, view the results, and review log and temp entries.
Identify the issue that causes the unexpected DITA preview results.

To diagnose the issue:

  1. Double-check your DITA publishing setup.
    Ensure the appropriate settings were in place when you executed the DITA preview.

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

    Check these settings in particular:
    • Ensure all Normalization Output Format settings are configured. Ensure the Rendering Schema for DSS field references the correct page schema. See Configuring DITA Open Toolkit Output Formats for details.
    • Ensure the DITA processor includes the normalized DITA output format, and ensure the normalized DITA output format has a partial match string in place for rendering the normalized DITA on the DSS.
  2. Run debug mode to include debugging details in the next DITA preview log.

    See Running DITA Debug Mode for details.

  3. Execute the DITA preview in the DITA Preview or XML tab, and check the DITA log to see if you run into errors.

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

  4. Check the DITA Preview or XML tab to review the output results.

    Note discrepancies, errors, or missing content that display in the preview. If no errors display in the DITA logs, then the issue may relate to the view stylesheet associated with the DITA page rendering schema.

    See Checking DITA Preview Output for details.
  5. Review the DITA temp folder for discrepancies within the temporary files that may relate to the issue.
  6. Interpret the log entry errors to determine what the conflicts entail.

Address Error Issues

Administrators can modify the DITA publishing pipeline setup and settings related to the DITA-OT. Users with asset editing permissions can resolve conflicts with DITA asset content and their dependencies, and they can modify settings applied at DITA preview time.

Use the information you gathered from troubleshooting to resolve DITA log entry errors.

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, preview the DITA asset again, and then review the DITA logs to see if the DITA preview logs contain errors. If issues persist, try another solution, or contact Ingeniux Support.