Skip to main content

RoboHelp to MadCap Flare: What Actually Breaks (And How to Fix It Before You Start)

· 5 min read
Mattias Sander
Mattias Sander

Every RoboHelp to Flare migration looks straightforward on paper. Flare even has a built-in RoboHelp import wizard. But the projects that come out the other side almost always need significant cleanup, and the problems are predictable if you know where to look.

Why the import wizard is not enough​

Flare's RoboHelp import gets you 70 to 80 percent of the way. It converts topics to XHTML, brings in your TOC structure, and maps most basic formatting. That last 20 to 30 percent is where teams lose weeks.

The wizard handles syntax conversion. It does not handle architectural translation. RoboHelp and Flare model content differently at a structural level, and those differences create silent problems that surface months later when you try to build, reuse, or scale.

Structural differences that matter​

Conditional content​

RoboHelp uses conditional build tags that work as simple include/exclude filters. Flare uses condition tags too, but with a more granular model: conditions can be applied at the topic, paragraph, span, and even attribute level, and they interact with targets through include/exclude/undefined logic.

When you import, RoboHelp's build tags come in as Flare condition tags. But the mapping is flat. If your RoboHelp project used build tags for multiple purposes — audience filtering, product variants, and output type control — those all land in a single condition tag set in Flare. Untangling them after import is tedious. Rearchitecting them before import saves significant time.

Stylesheets​

RoboHelp projects typically use a mix of inline styles, CSS classes, and RoboHelp-specific formatting. The import brings the CSS over, but it often arrives bloated with duplicate selectors, browser-specific hacks from older RoboHelp versions, and styles that have no equivalent in Flare's stylesheet model.

The practical impact: your Flare project starts with a stylesheet that is 3 to 5 times larger than it needs to be, filled with rules that conflict with Flare's default behavior. Writers apply styles that look correct in the editor but render differently in the output.

TOC and browse sequences​

RoboHelp TOCs import into Flare TOCs, but the relationship between TOCs and targets works differently. In RoboHelp, you typically have one TOC per output. In Flare, multiple targets can share a TOC, and TOCs can reference other TOCs. The import creates a one-to-one mapping that misses opportunities for reuse and often duplicates navigation structures.

Variables and snippets​

RoboHelp user-defined variables import cleanly. But RoboHelp does not have a snippet equivalent with the same flexibility as Flare's snippet system. Content that was copy-pasted across topics in RoboHelp — which is common because RoboHelp's reuse options are limited — stays duplicated in Flare. You now have a reuse tool but duplicated content that should be using it.

RoboHelp index keywords import into Flare, but Flare handles search differently. RoboHelp's search configuration, synonyms, and excluded words do not transfer. If your users depend on search, you need to rebuild the search configuration from scratch.

What breaks silently​

The worst migration problems are the ones that do not produce errors. Everything imports. Everything builds. But the output has issues that only surface during review or, worse, after publishing.

Image paths. RoboHelp and Flare handle image references differently. Imports often create references that resolve in the editor but break in specific output types, especially PDF targets.

Cross-references. RoboHelp hyperlinks between topics come in as basic anchor links. Flare's cross-reference system, which automatically updates link text and tracks broken references, is not used. You have working links with none of Flare's link management benefits.

Master pages and layouts. RoboHelp's master page concept does not align with Flare's master page model. The import does not create Flare master pages. Your topics arrive without the layout framework that Flare outputs depend on.

Character encoding. Older RoboHelp projects sometimes contain non-standard character encoding, especially in projects that were upgraded through multiple RoboHelp versions. These characters import without errors but render as garbled text in specific output formats.

Pre-migration checklist​

Before you run the import wizard, work through this list. Each item takes minutes to check and can save days of post-migration cleanup.

  1. Inventory your conditions. List every build tag and what it controls. Group them by purpose: audience, product, output type, or temporary flags. Plan your Flare condition tag architecture before import.

  2. Clean your stylesheet. Remove unused styles, inline formatting, and RoboHelp-specific CSS. The cleaner your source CSS, the cleaner the import.

  3. Audit cross-references. Identify all topic-to-topic links. Decide which should become Flare cross-references versus which should remain hyperlinks.

  4. Identify reuse candidates. Find content duplicated across topics. Plan which pieces become Flare snippets. It is far easier to create the snippet architecture during migration than to retrofit it later.

  5. Test with a subset. Import 20 representative topics first. Build every target type you need. Review the output carefully. The problems you find in 20 topics will be the same problems across 2,000.

  6. Document your mappings. Create a mapping document that records how each RoboHelp element translates to its Flare equivalent: conditions, styles, variables, and file structure.

The cost of skipping preparation​

Teams that run the import wizard without preparation typically spend 2 to 4 weeks on post-migration cleanup for a project with 500 or more topics. Teams that invest 3 to 5 days in pre-migration planning and source cleanup cut that to a few days.

The difference is not about the import tool. It is about understanding the structural gap between the two platforms and closing that gap before the content crosses over.

If your Flare project already went through a rough migration and is carrying structural debt from its RoboHelp origins, run the free Flare Bottleneck Diagnosis to identify the highest-impact areas to fix first. Or get in touch if you want hands-on help planning or executing a migration.