So you've decided to move your documentation from MadCap Flare to Archbee. Good. Now you need a plan: what happens to your content, what needs rebuilding, how long it takes, and what the process actually feels like day-to-day.
This guide skips the "should I switch" debate. Instead, it walks through what real teams experience during their own MadCap Flare migrations, answering the questions people actually asked along the way.
One thing worth knowing upfront: you're not doing this alone. Migration isn't a self-serve export you're left to sort out - it's a guided process with a real team working alongside you, from the first sample import through go-live and beyond.
Even when you're confident in the migration decision, it can still feel like a lot to hold in your head at once - especially if you've got years of snippets, variables, and reused content built up in Flare. This guide is meant to make that feel concrete instead of abstract.
The support behind migration#
Before getting into the step-by-step process, here's what stays true across the whole migration:
- Guided content migration
Your documentation gets brought over from Flare with real guidance at each step - not handed back to you as a DIY export project you're left to rebuild from scratch. - Structured setup that actually scales
Content isn't just dropped in as-is. It gets reorganized into a clear structure - spaces, products, audiences - so managing it going forward is easier, not harder, especially if you're consolidating multiple existing sites or portals. - Access, workflows, and reuse set up correctly
Access control, versioning, and reusable content are deliberately set up, so the workflows you rely on today are preserved without the complexity that usually slows teams down after a migration. - Phased rollout, no disruption to your team
You can start with one product or team, validate the setup, and expand gradually - without interrupting the documentation your team is actively using in the meantime. - Hands-on support from start to finish
From planning through rollout, there's a real team working closely with you to make sure everything is set up right - and that continues after go-live, not just during the move. Many migrations also include hands-on training sessions after launch, where your team is walked through how to make the most of Archbee day-to-day and how to actually work in the new tool going forward. Teams rate the support and setup experience at 9.2/10 for quality of support and 9.3/10 for ease of setup, based on independent G2 reviews.
The 5 phases of MadCap Flare to Archbee migration#
Migrating documentation can feel like an all-or-nothing leap. It isn't. Here's how it actually breaks down:
1. Sample
A small, real slice of your content - a few articles, maybe one space - gets migrated first, as a proof of concept. This isn't a demo with placeholder text; it's your content, so you can see exactly how it behaves before committing to anything larger.
2. Migrate
Once the sample is approved, Archbee migrates the remaining documents space by space and maps their hierarchy to the appropriate Archbee structure. The migration team checks all imported content elements, including tables, images, links, and callouts, and handles Flare-specific functionality such as snippets, variables, and conditional content, according to the agreed scope.
3. Validate
After the Archbee team imports and reviews the content, you and your team validate the migrated documentation. You confirm that the structure, formatting, images, links, and other content elements came across correctly and flag anything that still needs adjustment. Archbee then addresses migration-related issues before the final cutover.
4. Refine
Archbee works through the feedback collected during validation, resolves the identified issues, and performs a final QA pass. This process continues until the content is ready to launch.
5. Cutover
Once refinement is complete, your team confirms that the migration meets the agreed requirements. You can then connect your domain and publish the migrated documentation.
Throughout all five phases, you're working with dedicated onboarding support - not a self-serve tool you're left to figure out on your own. And it doesn't stop at go-live: ongoing support (typically responding in well under a day) and a dedicated point of contact carry through after migration too, so questions that come up weeks later get the same attention as those that come up on day one.
A real migration timeline
As a rough rule of thumb: plan for about four to six weeks for your migration - typically a week to evaluate your documentation and scope the work, two to three weeks to migrate and validate the content, and a final stretch to refine and cut over once everything's signed off.
This is what Cross River team mentioned about their migration experience from Madcap Flare to Archbee:
“For the migration, we provided all the source files from Madcap Flare. The Archbee team did most of the "heavy lifting" of converting the HTML files to MD. Our existing HTML API files were copied and pasted bit-by-bit into the new MD. They were extremely responsive.”
Devra Ariel
Sr. Documentation Specialist,
Cross River
Content migrated by category
A quick note before the breakdown: anywhere below that says "manual" or "rebuilt," that work is done by the migration team, not by you - nothing here is homework left on your plate.
- Content & Formatting Tables, images, numbered and bulleted lists, bold and italic text - these generally come across automatically and correctly. Icons or inline images often import consistently, but they might require manual cleanup to display in-line.
- Snippets & Variables Reused content blocks, variables, and conditional text do not survive a raw import. This isn't a bug - it's expected. These get rebuilt via automated scripts, while some may need manual work.
- Links & URLs Source CSH ID links get replaced with ID-based dynamic “doc mentions”, which stay intact, providing internal link reliability even if you reorganize your content later. Your production URLs can be preserved through custom URL settings, so existing bookmarks and cross-references don't break when you go live.
Where to go from here#
If you've read this far, you likely already have a good sense of what your migration will actually involve. The details will vary depending on your content, but the process follows the same shape: we start small, validate before scaling, migrate content and single-source elements, and cut over without losing what your team has already built.
The next step, if you haven't already, is simple: contact us for a knowledge base audit and get visibility on what your MadCap Flare migration would actually look like. That's how nearly every migration in this guide actually started - with a clear look at your own content and what moving it would involve, without an initial commitment.
Frequently Asked Questions
Mostly, yes - but not on the first pass. Notes, tips, warnings, numbered and bulleted lists, bold, italics, and dropdowns all get covered by the migration service. Because Flare exports HTML and Archbee renders Markdown, there's no true one-to-one automated conversion for every syntax variation Flare generates - some of it is handled programmatically, and the rest is rebuilt manually as part of migration.
The key thing to know is that a raw import you perform yourself will never reflect the final migrated state. That's expected, not a sign something's wrong - the migration service replaces the HTML-based structure programmatically with proper Markdown and MDX syntax so everything renders correctly and consistently.
Yes - and this is worth raising early during project discovery and planning. If your HTML contains clearly tagged elements (e.g., snippets marked as snippets, variables marked as variables), more can be identified and mapped automatically. If your export flattens everything into plain content with no distinguishing tags, the structure is lost and must be rebuilt manually.
In practice, this gets handled directly: you share both your published output and your source files (a ZIP export, or a link to a Git repository or wherever your HTML lives), and the migration team compares the two to map things correctly - rather than you having to go through and manually replace formatting page by page.
Yes - and if you're evaluating a migration, this is genuinely the best way to de-risk the decision. A sample migration on a real slice of your content (not a generic demo) shows you exactly how your tables, images, callouts, and structure behave in the new tool, before any commitment is made.
Some will import automatically; however, a raw HTML import doesn't carry over the underlying reuse logic - the thing that lets you write something once and have it appear in ten places. It is encouraged to communicate about their existence beforehand rather than to discover them mid-migration.
These elements are fully supported in the destination and get rebuilt properly as part of the migration service, based on your product structure and requirements - not left for your team to reconstruct by hand.
No, and this is probably the single most important thing to understand before testing anything yourself. A trial or raw import done via built-in importing options isn't meant to represent the finished product - it's a starting point for evaluation. Inconsistent icons, missing snippets, and formatting that isn't quite right are expected at this stage, and they're exactly the things the migration service addresses before anything goes live.