Importing DITA

Use the Paligo Import Wizard to import DITA content directly into Paligo. During the import, Paligo will handle most of the common DITA content elements, including conrefs (partially). If your content has DITA constructs that Paligo does not support, these may be excluded or imported as DocBook elements that have a different purpose. It is possible that this could result in invalid DocBook XML. These need to be corrected manually post-import.


Conkeyrefs used as variables can be automatically converted into variables and variable sets in Paligo. If you have used any other constructions for emulating variables in DITA, you may want to change to using conkeyrefs before you import into Paligo. This will allow the import to handle conversion of variables.

The following structure works:

  • A topicref or keyref with the attribute keys set on it

  • The topic referred to has phrase or keydef elements with id attributes.

  1. Prepare your DITA content and then zip the folder that contains it.

  2. In a folder with your DITA content, make sure you have one main ditamap file. Name this ditamap file: 


    If you have one ditamap for the entire publication, and several "chapter" ditamaps, only select and rename the main publication one. It does not matter if that's a regular ditamap or a bookmap.

  3. In Paligo's Content Manager, find the folder that you want to contain the DITA import content. Or you can create a new folder if you prefer.

  4. Select the options menu ( ... ) for the folder and then select Import Content to display the Import Wizard.

  5. Select DITA (.ditamap) as the import type and then select your DITA zip file as the "archive file".

    Import Content dialog with settings in place for importing DITA content.
  6. Select the parameters on the General options tab:

    • Check the Try to match components with existing components box if you want Paligo to recognize components that are identical to components that already exist in Paligo. When this is enabled, Paligo will not import content that already exists and will reuse the existing content instead. We recommend that you check the box so that your imports are more efficient and take advantage of Paligo's content reuse capabilities.

    • Choose whether you want to Import admonitions as separate components. We recommend that you check this box if you know you have many identical admonitions (notes, warnings, etc). But if most are unique, leave it unchecked.

    • Choose whether you want to Ignore warnings on import validation. In most cases, we recommend that you check this box unless you have problems when trying the import. Paligo will usually fix minor problems automatically during the import process.

  7. Use the Custom options tab to set:

    • Adding a title prefix: Use this setting if you need to mark your imported topics with a prefix. Enter the prefix in the field. If you do not need a prefix, leave the field blank.

    • Enable folder numbering: Use to add sequential numbering to the folders for your imported content.

    • Max folder levels: Use to control the maximum number of folder levels Paligo will create for your imported content. By default Paligo will create a folder structure that matches the structure of your import content down to the second level. For example, if you have a manual with chapters and sub sections, the import will create a folder for each "chapter" and the first level under that.

    • Match with existing variable set: Paligo can create variable sets from DITA and MadCap Flare import content, and this setting only applies to those.

      If you import a format that creates variable sets, and this is the first time you are importing the content, leave this field blank. This will mean that Paligo creates a variable set for your content.

      If you have imported the content before, or it already exists in Paligo, enter the ID of the variable set in Paligo. Paligo will then match the import content to the existing variable set and will not create a duplicate.


      To find the variable set ID, open the variable set and look at the URL in the browser's address bar. The ID is immediately after "edit/".

      Paligo will collect multiple variable sets into one. After the import, you can separate them into multiple variable sets again if required.


      It is possible to configure the import to make translatable variables (the default is plain text variables). For translatable variables, please contact support to ask to have the parameter variable.type set to "translation".

  8. Select OK to start the import.

Paligo imports the content into the Content Manager. When the import is complete, check the content as you may need to alter some of it manually (if there were DITA elements that are not supported by the Paligo import, for example).