Skip to content

Import from DITA

Import DITA XML files, either individual topics or full DITA maps with their topic hierarchies. 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

  • If importing a DITA map, include all referenced topic files in a single .zip archive

Plan your migration

Before importing, assess your DITA content:

  1. Import the whole project, not loose topics. How much transfers depends on what you import. A single .dita file becomes one topic. A full DITA project, meaning a .ditamap (or two or more .dita topics) plus its referenced files zipped together, unlocks the high-fidelity path that also reconstructs conrefs, conditions, relationship tables, and DITAVAL targets. Whenever possible, zip and import the project.

  2. Check for conrefs. In a project import, conref targets are turned into Topicary components and each conref usage becomes a component reference, so single-source reuse carries over. In a single-file import there is no project context, so the referenced content is inlined instead.

  3. 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"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<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 map

  1. Select a .ditamap file along with its referenced topic files, or a .zip containing everything.

  2. Click Import.

The DITA map's <topicref> hierarchy becomes nested map items in Topicary. When you import a project, Topicary builds the map from the ditamap automatically, so there is no checkbox to set. (The "Create a map from folder structure" checkbox appears only when you select several loose files at once without a ditamap to drive the hierarchy.)

The ditamap-to-map conversion is one of the cleanest parts of a DITA migration. Your <topicref> nesting, topic ordering, and section grouping are preserved as Topicary map items, so you rarely need to reorganize after import.

What is preserved

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

DITA element

Topicary equivalent

<concept>

Topic (type: Concept)

<task>

Topic (type: Task)

<reference>

Topic (type: Reference)

<glossentry>

Topic (type: Glossary)

<topicref> nesting

Map hierarchy

<p>, <ul>, <ol>, <dl>, <table>

Paragraphs, lists, definition lists, tables

<codeblock>

Code block

<note>

Callout block

<xref>

Topic link or regular link

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:

DITA structure

Topicary equivalent

Conref targets

Components, with each conref usage kept as a component reference

Profiling attributes (@audience, @platform, @product, …)

Condition dimensions and values

DITAVAL files

Publication targets with the matching condition profile

Relationship tables

Topic links between the related topics

Subject scheme maps

Condition dimension values in project settings

Bookmap roles (chapter, frontmatter, backmatter)

Map item metadata

Prolog metadata, nested/ditabase topics

Topic metadata; nested topics split into separate topics

These reconstructions require the surrounding project. A lone .dita file imported on its own has no map, DITAVAL, or sibling topics to draw from, so its conrefs and key references are inlined and its profiling attributes are not turned into conditions. Zip and import the project to get the high-fidelity path.

What is not preserved

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

  • Key definitions and key references: resolved (inlined) at import time

  • 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

Post-import checklist

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

  2. For a project import, open a few topics that used conrefs and confirm the component references resolve; for a single-file import, identify content that was inlined and extract it into components.

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

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

  5. Confirm the topic links reconstructed from relationship tables point where you expect.

  6. Publish a test target and review the output.

See also

Was this page helpful?