Migrate from MadCap Flare to Topicary

How to Migrate from MadCap Flare to Topicary

Migrating from MadCap Flare is not as painful as it looks. A Flare project is a folder of XML files with known structures — topics, snippets, TOC, variables, conditions — and Topicary's importer reads all of them. If you are not yet familiar with what a CCMS is, that guide explains the component-based model Topicary uses. The automated import takes under a minute. The real work is the 1 to 3 days of manual cleanup afterward: recreating publishing targets, verifying component references, and simplifying any condition logic that relied on Flare's boolean expression builder.

This guide walks through the entire process, from auditing your Flare project before you export it to validating the migrated content in Topicary. If you are evaluating whether to migrate at all, read the detailed Topicary vs MadCap Flare comparison first.

Why teams are leaving Flare in 2026

The primary driver is pricing. MadCap discontinued perpetual licenses — new customers must subscribe at $2,999/yr per seat (madcapsoftware.com/pricing/, checked May 2026). Multiple Flare customers on r/technicalwriting reported a 45% renewal price increase in late 2025, with renewals hitting in early 2026. One user described the situation bluntly: "MadCap wants to increase their rates by a whopping 45%, and I've been asked to look around for alternatives." Another confirmed the same renewal timeline and extension length.

Vendr procurement data (checked May 2026) reports a ~9% annual uplift on MadCap subscription renewals as standard practice (vendr.com). A 5-writer team paying list price spends $14,995/yr on Flare desktop licenses alone — before adding Flare Online for cloud hosting, review, and AI features.

The price increase is the trigger, but it is not the only reason. Teams also cite Flare's Windows-only desktop requirement (Mac users need Parallels), the learning curve (Capterra Ease of Use: 3.5/5 across 21 reviews, checked May 2026), and Git-based collaboration friction as factors pushing them toward cloud-native alternatives.

Before you export: audit your Flare project

Do not start the import until you know what you have. Migrations that skip the audit phase are the ones that go over budget — Improvementsoft reports that roughly 80% of CCMS migrations run over budget or over schedule, primarily because teams migrate first and discover structural problems later.

Take inventory of your content

Open your Flare project and document the following:

• Topic count — how many HTM files live in your Content folder
• Snippet count — how many .flsnp files you have and where they are referenced
• Condition tags — which dimensions you use (audience, platform, product) and whether you rely on boolean expressions (AND/OR/NOT)
• Variable sets — how many .flvar files and whether you use system variables (page numbers, dates) or target-level overrides
• TOC files — how many .fltoc files, and whether they reference topics across multiple projects through Global Project Linking
• Custom stylesheets — any CSS overrides beyond Flare's defaults
• Micro content — any micro content topics that power search results or chat widgets
• Target count — how many publishing targets you maintain (HTML5, PDF, Word, and others)

Decide what to leave behind

Every piece of content you do not migrate is content you never have to restructure, maintain, or troubleshoot in the new system. Improvementsoft's migration consultancy recommends budgeting 20 to 30 percent of total migration time for validation and cleanup — cutting dead content before import reduces that budget significantly.

Look for topics that have not been updated in over a year, snippets that are referenced zero times (Flare's "Used By" column in the File List shows this), and condition tags that no active target uses. Archive or delete these before exporting.

Step 1: Export your Flare project as a zip

Locate your .flprj file and the enclosing project folder. A typical Flare project folder looks like this:

MyProject/
├── MyProject.flprj
├── Content/
│   ├── Topics/
│   │   ├── getting-started.htm
│   │   ├── installation.htm
│   │   └── ...
│   └── Resources/
│       ├── Snippets/
│       │   ├── copyright-notice.flsnp
│       │   └── ...
│       └── Stylesheets/
│           └── MainStyles.css
└── Project/
    ├── TOCs/
    │   └── OnlineOutput.fltoc
    ├── Variables/
    │   └── General.flvar
    └── Targets/
        ├── HTML5.fltar
        └── PDF.fltar

Zip the entire folder — the Content and Project subdirectories must both be included. Topicary needs the .flprj file to identify the project, the Content folder for topics and snippets, and the Project folder for TOC structure, variables, and conditions.

If your project uses Global Project Linking across multiple Flare projects, zip each project separately. Each one must be imported as its own Topicary project.

Step 2: Import into Topicary

Open the Topicary import dialog (drag the zip file onto the editor, or use the import button in the project toolbar). Select "MadCap Flare" as the source format. Topicary's importer parses the project structure and shows a preview before committing anything:

• Topics detected — count and list of HTM files that will become Topicary topics
• Components detected — snippets (.flsnp files) that will become reusable components
• Variables — variable sets with key-value pairs
• Conditions — condition dimensions and values extracted from the project file
• TOC hierarchy — map structure with nesting preserved

Review the preview. If the counts look wrong — far fewer topics than expected, or zero snippets when you know you have them — check that your zip includes the full project folder structure. The importer expects the Content and Project directories at standard paths relative to the .flprj file.

Step 3: Verify what transferred

After the import completes, open the project in Topicary and check these five areas.

Topics

Each Flare HTM file becomes a Topicary topic. The importer preserves heading structure (H1 through H6), paragraphs, ordered and unordered lists, tables, images, and code blocks. Inline formatting — bold, italic, code, links — carries over.

What does not carry over: Flare-specific MadCap elements like MadCap:dropDown, MadCap:expanding, MadCap:toggler, and MadCap:popup are stripped during import. Content inside these elements is preserved as plain paragraphs, but the interactive behavior is lost. If your project relies heavily on dropdown sections, plan to restructure those topics manually.

Components (snippets)

Flare snippets (.flsnp files) become Topicary components. Every reference relationship is preserved — if a topic referenced a snippet in Flare, the corresponding Topicary topic will contain a component reference to the imported component.

Check the component "Where Used" list in the Components panel to verify reference counts match your expectations. Orphaned components (referenced zero times) may indicate broken references that need manual reconnection.

TOC structure (maps)

The .fltoc file becomes a Topicary map with nesting preserved. Topic order, hierarchy depth, and grouping all transfer.

TOC entries that pointed to external URLs, PDFs, or other non-topic resources will appear as placeholders. Review the map and remove or replace these entries.

Variables

Variable sets (.flvar) transfer as key-value pairs. Open the Variables panel and confirm that variable names and default values match your Flare project.

What does not transfer: system variables (page numbers, build dates, heading text), target-level variable overrides, and date/time variables. If you relied on per-target variable values in Flare — for example, a "ProductName" variable that resolved differently in your internal versus customer-facing targets — you will need to manage this through Topicary's condition system or maintain separate variable sets.

Conditions

Condition tag sets become Topicary condition dimensions and values. If your Flare project had a "Platform" condition set with values "Windows", "macOS", and "Linux", Topicary will create a "Platform" dimension with those three values.

What does not transfer: boolean condition expressions. If your Flare targets used expressions like (Platform="Windows" AND Audience="Admin") OR (NOT Feature="Deprecated"), those expressions have no equivalent in Topicary. You will need to simplify them to per-block include/exclude rules, or use nested conditional blocks as a workaround for AND logic. For most teams with 2 to 3 condition dimensions, the simplification is straightforward. Teams with 5+ overlapping dimensions should evaluate whether Topicary's condition model meets their needs before committing to the migration — the comparison page covers this trade-off in detail.

Step 4: Recreate what does not transfer

Some Flare capabilities are platform-specific and require manual recreation in Topicary. Budget the bulk of your migration time here.

Publishing targets

Flare targets (.fltar files) do not transfer. In Topicary, set up publication targets for each output you need:

• Web output — create a publication, configure branding (color, font, logo, favicon, custom CSS), and publish. Topicary hosts the site for you — no S3, Netlify, or FTP configuration needed.
• PDF output — configure the PDF target with your cover page, running headers, footer text, and font selections. Topicary generates print-optimized PDFs with a table of contents, page numbers, and dot leaders. Note: if your Flare PDF targets relied on auto-numbering, back-of-book index generation, or master page layouts, those features do not exist in Topicary's PDF engine.
• Markdown export — available for any map or individual topic. Useful for feeding documentation into developer workflows or static site generators.

Custom stylesheets and skins

Flare's CSS stylesheets and HTML5 skins do not transfer. Topicary uses a branding system instead: set your primary color, logo, fonts, and favicon in the project settings. For deeper customization, the Team plan includes a custom CSS field that applies to published sites.

If your Flare project had extensive CSS customization for PDF output (custom page margins, font stacks, column layouts), those will need to be simplified to Topicary's PDF configuration options or applied through custom CSS where supported.

Micro content

Flare's micro content feature — short answer snippets that power search results and AI chat — has no direct equivalent in Topicary. Consider converting micro content topics into standard FAQ-style topics. Topicary's published sites include AI-powered search that extracts answers from your existing content, which covers some of the same use cases without requiring dedicated micro content entries.

Cross-references

Flare cross-references that resolve to page numbers ("See 'Installation' on page 42") become standard topic links in Topicary. The web-first model links to topics by name rather than page number. For PDF output, these render as clickable links — not page number references.

Step 5: Validate and publish

After recreating your publishing targets, run through a validation checklist before publishing.

• Spot-check 10 to 15 topics across different sections. Verify formatting, heading levels, and list structure.
• Open every component and confirm its content matches the original Flare snippet. Check the "Where Used" count.
• Preview with conditions applied. Toggle each condition dimension in the editor and verify that the correct content appears and hides.
• Replace variables. Open a topic that uses variables and confirm they resolve to the expected values.
• Publish a test site. Publish to a draft URL, navigate every page, and check that the TOC hierarchy matches your expectations.
• Generate a test PDF. If you use PDF output, generate one from your main map and compare it against your Flare PDF. Note the formatting differences you can live with and the ones you cannot.

For large projects (200+ topics), consider a phased migration: import the full project, validate and publish one section at a time, and use the old Flare site as the reference while you work through each section. Improvementsoft recommends budgeting 20 to 30 percent of the total migration time for validation and cleanup — this is not wasted time, it is the phase that prevents problems from reaching your readers.

Realistic timelines

Migration timelines depend on project size and how heavily you use Flare-specific features. Here are realistic estimates based on the import capabilities and what requires manual work.

These estimates assume one writer doing the migration work. With a second writer handling validation while the first continues cleanup, you can compress the medium and large timelines by roughly 30%.

What you gain after migration

The migration effort buys you a permanent shift in how your team works:

• No more merge conflicts. Multiple writers work on different topics simultaneously in the browser. No Git, no SVN, no source control overhead.
• Hosted publishing with zero infrastructure. Publish and the site is live — with dark mode, full-text search, AI search, and reader feedback included. No servers to deploy or CDNs to configure.
• SME review without barriers. Generate a review link, send it to your subject matter expert. They open it, read, comment, and approve — no account, no install, no training.
• LLM-ready output. Every published site automatically generates llms.txt, .md page URLs, sitemap.md, and an AI query endpoint. Your documentation is consumable by AI agents out of the box.
• Predictable pricing. Topicary Team covers up to 10 authors at $149/mo ($1,788/yr). No per-seat licensing, no hidden Flare Online add-on costs. For comparison, 5 Flare desktop seats cost $14,995/yr before Flare Online. Currently free during beta — join here.

For a deeper look at what each tool does better and the honest trade-offs, read the full Topicary vs MadCap Flare comparison. To understand how Topicary fits into the broader CCMS market, see Why I Built Topicary.

Frequently asked

How long does the import take?

The automated import takes under a minute for most projects — Topicary parses the zip file, identifies topics, snippets, TOC structure, variables, and conditions, and creates the corresponding Topicary objects. The import speed is not the bottleneck. Manual cleanup and validation is where the real time goes: 1 to 3 days for small projects, 1 to 2 weeks for large ones with heavy use of Flare-specific features.

What happens to my Flare drop-downs and expanding text?

Flare's interactive elements — MadCap:dropDown, MadCap:expanding, MadCap:toggler, and MadCap:popup — are stripped during import. The content inside them is preserved as standard paragraphs or list items, but the collapsible or interactive behavior is lost. If your project uses drop-downs extensively, plan to restructure those sections into separate topics or use Topicary's callout blocks for important notes.

Can I run Flare and Topicary in parallel during migration?

Yes, and you should. Keep your Flare project live and publishing while you validate the Topicary import. Publish the Topicary site to a draft URL for internal review. Once you have validated every section, switch your public documentation URL to the Topicary-hosted site. This parallel period typically lasts 1 to 2 weeks for medium projects.

Do I need to know XML to use Topicary?

No. Topicary uses a block editor with slash commands and a floating toolbar — similar to Notion or Google Docs. There is no XML view, no markup to write, and no schema to learn. Components, conditions, and variables are visual elements you insert from the editor, not XML tags you type. For writers coming from Flare, this is the single biggest workflow change — and the one most teams describe as a relief rather than a loss. For more on this approach, see structured authoring without XML.

What if I need features Topicary does not have?

Be honest about your requirements before migrating. If your team needs print-production PDF with auto-numbered sections and back-of-book indices, boolean condition expressions across 5+ dimensions, offline authoring in air-gapped environments, or output to formats like EPUB, PowerPoint, or CHM — Flare remains the stronger choice for those specific capabilities. Migrating to save money and then discovering a feature gap is more expensive than renewing Flare for another year. The comparison page lists every capability gap with specifics.

Disclosure: This guide is published by Topicary. I compete with MadCap Flare and have a commercial interest in teams migrating. I have tested the Flare importer against real Flare projects and cite specific sources for every factual claim. All pricing checked against madcapsoftware.com/pricing/ on May 26, 2026. If you find an error, email support@topicary.com and I'll correct it within 24 hours.