Skip to main content

Import from 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 conkeyrefs (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.

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).

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


    If you use variables in your DITA content and want to import them into Paligo as variables, see Import Conkeyrefs as Variables.

  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 rename the main publication one. It does not matter if that's a regular ditamap or a bookmap.

  3. Use the Import Wizard to import your DITA content.

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

If you have used conkeyrefs for variables in DITA, Paligo can import them as variables and variable sets in Paligo. For this to work, you need:


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

If you have any trouble with this, ask support for instructions about how to prepare the content.

  1. A ditamap that contains a topicref to a topic and a keydef to the variable file. For example:

    <topicref href="topics/DITA-topic-w-vars.dita"/>
    <keydef keys="products" href="topics/DITA-variables.dita"/>
  2. The variable file, which is a topic with each variable declared with an ID. For example:

     <p>Product name: <ph id="productname">product A1</ph></p>
  3. A topic that contains references to the variables, such as:

    <p>This is the product name: <ph conkeyref="products/productname"/></p>


    • "products" is the id of the variable file, as given in the ditamap keydef

    • "productname" is the id of the variable.

  4. When you have these files, add them to a folder and zip the folder.

  5. Use the Import Wizard to import your content.

    When the import is complete, Paligo will import the variable file as a variable set and will import the conkeyref elements into variables.


To learn more about variables and variable sets in Paligo, see:

The example below shows what happens when you import DITA content with variables into Paligo (assuming the DITA content is set up correctly).

Example 1. DITA files for importing conkeyref as variables

The zip file contains a folder and inside the folder are:

  • index.ditamap

    A ditamap that contains a topicref to a topic (DITA-topic-w-vars.dita) and a keydef to the variable file (DITA-variables.dita)

  • DITA-variables.dita

    This is the variable file, where each variable is declared with an ID.

  • DITA-topic-w-vars.dita

    This is a topic that contains conkeyref references to the variable file (DITA-variables.dita).

The content of the files is:


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
    <title>DITA map with variables</title>
    <topicref href="topics/DITA-topic-w-vars.dita"/>
    <keydef keys="products" href="topics/DITA-variables.dita"/>


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="DITAvariables">
        <p>This is an example of a DITA variable file</p>
        <p>Here is the variables enclosed in PH-tags with Ids:</p>
        <p>Product name: <ph id="productname">product A1</ph></p>
        <p>Product type: <ph id="producttype">produkttype A1</ph></p>


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="dita_topic_w_vars">
    <title>DITA topic with variables</title>
        <p>This is an example of a topic using variables as conkeyrefs.</p>
        <p>This is the product name: <ph conkeyref="products/productname"/></p>
        <p>This is the product type: <ph conkeyref="products/producttype"/></p>

When you import this zip into Paligo, Paligo generates:

  • A publication that contains a fork to the topic that Paligo creates for the DITA-topic-w-vars.dita file.

    Paligo has created a publication for a DITA import. The publication contains a fork to a "DITA topic with variables" topic.
  • A topic with the content from the DITA-topic-w-vars.dita file, converted to Paligo XML with Paligo variables instead of conkeyref variables.

    A topic called "DITA topic with variables" shown in the Paligo editor. It has various paragraphs, two of which contain variables that reference a variable set.
  • A variable set. Paligo creates a variable set and imports the content of the DITA.variables.dita file into it. The imported data is converted into Paligo variables.

    A variable set that Paligo has generated automatically for an imported DITA variable file. It contains a variable for product name and a variable for product type. Both variables have a value set for a "general" variant.

    The values for the variables are in a "General" column. This represents the values to use for one variant. You can add extra variants so that the variables can have different values in different circumstances.