Skip to content

Import formats

Topicary imports content from eight formats.

Format

Extensions

Max size

What is created

Markdown

.md, .markdown

5 MB

Topics

HTML

.html, .htm

5 MB

Topics

Word

.docx

5 MB

Topics

DITA

.dita, .ditamap, .xml

5 MB

Topics + map (from ditamap)

Confluence

.zip (HTML export)

50 MB

Topics + map (from page hierarchy)

MadCap Flare

.zip (project)

50 MB

Topics, components, map, variables, conditions, publication targets, branding, images + downloads

OpenAPI

.json, .yaml, .yml

5 MB

Topics (an overview + one for each tag)

XLIFF 2.0

.xlf, .xliff

5 MB

Topics (merge, new, or translation mode)

Archive limits

  • Single files: 5 MB

  • Zip archives: 50 MB (200 MB decompressed)

The 50 MB limit applies to the compressed archive. The decompressed content must not exceed 200 MB. Imports that exceed either limit are rejected before processing begins.

What is preserved for each format

Markdown

  • Title from # H1, YAML frontmatter title, or filename

  • Headings, bold, italic, strikethrough, inline code

  • Bullet lists, ordered lists, task lists

  • Tables, code blocks with language hints, blockquotes, images, links

HTML

  • Semantic elements (headings, paragraphs, lists, tables)

  • Images, links, code blocks

  • Basic inline formatting

Word (.docx)

  • Heading styles → headings

  • Lists, tables, images (extracted and uploaded)

  • Bold and italic (underline is not carried over)

Word import relies on Word's built-in heading styles (Heading 1, Heading 2, and so on) to detect document structure. Text that is merely bolded or enlarged but not styled as a heading imports as a regular paragraph. Apply proper heading styles in Word before importing for the best results.

DITA

  • Topic types (concept → Concept, task → Task, reference → Reference)

  • Ditamap hierarchy → map structure

  • Standard DITA elements → paragraphs, lists, tables, code blocks, notes

Confluence

  • Page content with Confluence chrome stripped

  • Info/warning/note macros → callouts

  • Code macros → code blocks

  • Page hierarchy → map structure

MadCap Flare

  • Topics → topics (with image alt text and <meta name="description">)

  • Snippets → components (with references preserved)

  • TOC → map hierarchy

  • Variable definitions → variable sets (plus per-target overrides)

  • Condition tags → condition dimensions and values

  • Target condition expressions (including boolean exclude/include) → condition profiles

  • Targets → publication targets (web/PDF, with homepage and PDF cover/TOC settings)

  • Skin favicon + logo, master-stylesheet brand tokens + web font → project branding

  • Images and linked downloads (.sql, .zip, .pdf, …) → uploaded to storage with paths rewritten

Of all supported formats, MadCap Flare preserves the most content architecture. Snippets map to components, TOC to map hierarchy, variables and conditions carry over with their logic, targets become publication targets, and branding/images/downloads come along. If you are migrating from Flare, expect the smoothest transition.

OpenAPI

  • An overview topic (API title, base URL, version, contact)

  • One topic per tag, documenting each operation's method, path, parameters, and schemas (operations with no tag are grouped by their path)

  • Request/response examples preserved

XLIFF 2.0

  • Import translations from XLIFF files

  • Supports three modes: merge (update existing topics), new (create topics from XLIFF source), or translation (apply translations to existing topics for a specific locale)

  • Preserves conditional and variable markers

XLIFF files are imported from the Translation panel in the topic editor, not the Topics Import dialog, because importing a translation is part of the localization workflow. See Localize content for the full XLIFF round-trip.

What happens after a bulk import

When you import multiple files at once, Topicary runs an AI structuring pass over the newly created topics in the background. It does not change your content; it only proposes structure you can accept or dismiss:

  • Topic types: classifies each untyped topic as a concept, task, reference, FAQ, troubleshooting, tutorial, or overview, using the topic's headings and structure (and an AI model for ambiguous cases).

  • Component candidates: flags passages that repeat across imported topics as candidates to extract into a reusable component.

These appear as suggestions on the project Dashboard, each with an Accept or Dismiss action. Nothing is applied automatically, so you stay in control of how imported content is categorized and single-sourced.

The structuring pass runs on multi-file (bulk) imports on every plan, including the Free plan. Single-file imports skip it; you can still set topic types and extract components manually.

Drag and drop

You can also import files by dragging them directly onto the editor or any page in the dashboard, where a drop zone appears to accept the files. This works for every format that goes through the Import dialog (Markdown, HTML, Word, DITA, Confluence, MadCap Flare, and OpenAPI). XLIFF translations are imported separately from the Translation panel.

See also

Was this page helpful?