Import from DITA

Import DITA XML files, either individual topics or full DITA projects with their maps. DITA import is available on every plan, including the Free plan.

Before you begin #

• DITA content must be valid XML; resolve any parsing errors before importing

• Standard PUBLIC and SYSTEM DOCTYPE declarations are accepted without loading their DTDs. Files must be self-contained: internal DTD subsets and entity declarations are refused.

• To import a DITA map, put the .ditamap and every file it references in a single .zip archive. A .ditamap selected on its own is refused.

Plan your migration #

Before importing, assess your DITA content:

1. Import the whole project, not loose topics. A single .dita file becomes one topic. A full DITA project unlocks the high-fidelity path. That means a .ditamap (or two or more .dita topics) plus its referenced files, zipped together. The project path reconstructs conrefs, conditions, and DITAVAL targets. Whenever possible, zip and import the project.

2. Check for conrefs. In a project import, a conref to a whole topic becomes a Topicary component. Each conref usage becomes a component reference, so single-source reuse carries over. Conrefs to a single element inside a topic (file.dita#topic/element) are not supported. A topic that uses one is not imported, and the import results name it.

3. Check for key references. Keys defined in the .ditamap resolve for image references (<image keyref>) and for conkeyref. Text key references, such as <keyword keyref> and <ph keyref>, are not resolved. The element keeps only its own text.

4. Check for nested maps. A map that pulls in another map with <mapref> is not assembled. Flatten nested maps into one .ditamap before importing.

5. Identify specializations. Topics using specializations beyond concept, task, reference, and glossary are imported as generic topics. Review these for proper categorization.

Here is a typical DITA topic structure that Topicary imports:

<?xml version="1.0" encoding="UTF-8"?>
<concept id="backup_overview">
  <title>Backup overview</title>
  <shortdesc>How automatic backups protect your data.</shortdesc>
  <conbody>
    <p>The system creates daily backups of all project data.</p>
    <ul>
      <li>Database snapshots run at 02:00 UTC</li>
      <li>File storage is replicated across two regions</li>
    </ul>
    <note type="important">Backups are retained for 90 days.</note>
  </conbody>
</concept>

In this example, the <concept> type maps to a Concept topic and the <note> becomes a callout block. All standard elements (<p>, <ul>, <li>) transfer directly.

Import individual DITA topics #

1. Go to Topics and click Import.

2. Select .dita or .xml files.

3. Preview cards show each file's title and a format badge. The DITA topic type (concept, task, reference) is detected during import and set on the created topic.

4. Click Import.

Import a DITA project #

1. Select a .zip that contains the .ditamap and all the topic, image, and DITAVAL files it references.

2. Leave Create a map from imported structure selected. It is selected by default. Clear it only if you want the topics without a map; DITAVAL targets are then skipped too, because they need a map.

3. Click Import.

The DITA map's <topicref> hierarchy becomes nested map items in Topicary.

What is preserved #

Content elements transfer the same way for both single-file and project imports:

Additional structures preserved in a project import #

When you import a full DITA project (a .ditamap plus its files, or two or more .dita topics, zipped together), Topicary also reconstructs:

What is not preserved #

• DITA specializations beyond concept, task, reference, and glossary: imported as generic topics

• Conrefs to a single element (file.dita#topic/element): not supported; the topic that uses one is not imported

• Text key references (<keyword keyref>, <ph keyref>): not resolved; only image keys and conkeyref resolve

• Nested maps (<mapref>): the map is not assembled

• Images inside running text (an <image> within a paragraph): the topic is not imported; move the image to its own block first

• DITAVAL flag (highlighting) rules: only include/exclude rules become condition profiles

• DITA features without a Topicary equivalent (for example, complex domain specializations): review after import

When a topic or map cannot be imported completely, Topicary does not import a partial copy. The import results list each skipped item with the reason.

Post-import checklist #

1. Read the import results. Fix any topic or map listed as not imported, then import again.

2. Review imported topics for formatting accuracy, especially tables and nested lists.

3. For a project import, open a few topics that used conrefs and confirm the component references resolve. For a single-file import, find the content that conrefs would have pulled in and extract it into components.

4. Check the map hierarchy. DITA map topicref nesting maps to Topicary indentation.

5. Review the condition dimensions and values created from your profiling attributes. Confirm any publication targets created from DITAVAL files match the audience split you expect.

6. If your project used relationship tables, check the Related topics list at the end of a few related topics.

7. Publish a test target and review the output.

See also #

• Import formats: full reference for supported formats, size limits, and what content is preserved for each format

• Create and organize a map: adjust the map hierarchy created from your ditamap structure

• How component reuse works: work with the components created from your DITA conrefs (or extract new ones)

• Conditions versus variables: review and manage the conditions reconstructed from your DITA profiling attributes