Import from DITA

Import DITA XML files — individual topics or full DITA maps with their topic hierarchies. Import is available on Pro, Team, and Business plans.

Before you begin #

• You need a Pro, Team, or Business plan

• 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. Check for conrefs. DITA content references are resolved at import time — the referenced content is inlined into each topic. After import, create Topicary components manually for content you want to single-source.

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

3. Note relationship tables. Relationship tables are not imported. Recreate cross-references using Topicary's topic link feature after import.

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, the <note> becomes a callout block, and 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 the detected topic type (concept, task, reference) and title.

4. Click Import.

Import a DITA map #

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

2. Check "Create a map from folder structure" to preserve the map hierarchy.

3. Click Import.

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

What's preserved #

What's not preserved #

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

• Conrefs — resolved at import time (content inlined, not converted to components)

• Relationship tables — not imported

• DITA metadata (audience, platform, product attributes) — not mapped to Topicary conditions; set up conditions manually

• Conditional processing attributes (@audience, @platform) — not converted to Topicary conditions

• Key definitions and key references — resolved at import time

Post-import checklist #

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

2. Identify content that was conref'd in DITA and create Topicary components for blocks you want to reuse.

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

4. Set up condition dimensions for any DITA profiling attributes you were using (audience, platform, product).

5. Re-create cross-references that were in relationship tables using topic links.

6. Publish a test target and review the output.

See also #

• Import formats — Full reference for supported formats, size limits, and what content is preserved per format

• Create and organize a map — Adjust the map hierarchy created from your ditamap structure

• How component reuse works — Create components from content that was inlined from conrefs during import

• Conditions vs. variables — Set up conditions to replace DITA profiling attributes that were not imported