So you've made the call 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 experienced 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.
What this guide covers
- What you can count on, throughout - the support and structure that stays consistent across the whole migration, regardless of how big or complex your content is
- The phases of migration - the five-step process, from sample to cutover
- What a real timeline looks like - a week-by-week view of how long migration typically takes
- What actually gets migrated, by category - a breakdown of what comes across automatically vs. what gets rebuilt
- Frequently asked questions - the mostly asked concerns real MadCap Flare customers have raised, answered directly
What you can count on, throughout#
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 get set up deliberately, 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 a hands-on training session after launch, where your team gets walked through how to make the most of Archbee day to day - not just how the migration went, but 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:
- Sample - A small, real slice of your content is migrated first, before anything else.
- Migrate - Once the sample looks right, your content moves in space by space.
- Validate - You and your team review the raw import before anything goes live.
- Rebuild single-sourcing - Snippets, variables, and conditional text get rebuilt manually to match your structure.
- Cutover - Links go live, your domain connects, and existing bookmarked links keep working.
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 looks right, the rest of your content gets imported space by space. This is a direct, raw import - your Flare HTML output gets translated into Archbee's structure. Tables, images, and inline elements typically come across cleanly at this stage.
3. Validate
This is the phase people underestimate. The raw import is a working draft, not the finished product. You and your team review it - broken tables, missing thumbnails, image resolution issues, outdated brand colors pulled in from an old file - and flag anything that needs fixing. This is expected at this stage, not a red flag.
4. Rebuild single-sourcing
Snippets, variables, conditional text, and CSH IDs don't survive a raw import - they're not broken, they're just not there yet. This is the phase where they get manually rebuilt, based on how you want your content structured going forward. Icon placement and callout styling get finalized here too.
5. Cutover Once everything's validated and rebuilt, links switch from placeholders to permanent internal links, your domain connects, and your existing URLs redirect cleanly - so nothing your customers have bookmarked breaks.
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 ones that come up on day one.
What a real migration timeline can look like#
As a rough rule of thumb: plan for about 4 weeks for a straightforward migration. If your documentation leans heavily on snippets and reused content across multiple products, expect the "rebuild single-sourcing" phase to take longer - that part is done by hand, and it shouldn't be rushed.
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. 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
What actually gets 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 (including inline images), numbered and bulleted lists, bold and italic text - these generally come across automatically and correctly. Icons are the exception: they often import inconsistently at first and need manual cleanup to display in-line the way you're used to.
- 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 manually, mapped to how your content is structured today.
- Branding & Styling Flare's "Mediums" (its built-in styling system) don't transfer directly - Archbee uses standard CSS instead. If your current styling is heavily customized, this is worth treating as its own conversation rather than assuming it comes along for free.
- Links & URLs CSHIDs get replaced with ID-based dynamic links, which stay intact 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.
Frequently Asked Questions#
Will all the styles in our content convert to an equivalent style in Archbee?#
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: the raw import you might test 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 with proper Markdown so everything renders correctly and consistently.
When we decide to move things over, can we coordinate how that's done?#
Yes - and this is worth raising early rather than assuming it'll sort itself out. If you export clean HTML with clearly tagged elements (snippets marked as snippets, variables marked as variables), more can be identified and mapped automatically. If your export flattens everything into plain HTML with no distinguishing tags, that structure is lost and has to be rebuilt manually.
In practice, this gets handled directly: you share both your published output and your source files (an export, or a link to a GitHub repo or wherever your HTML lives), and the migration team compares the two to map things like callouts correctly - rather than you having to go through and manually replace formatting page by page.
Can you show us a small sample first?#
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.
What happens to our variables, conditional tags, CSH IDs, and snippets? Are they imported automatically?#
No - they're not imported automatically, but they're not lost. 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. This is one of the most common surprises for teams migrating off Flare, and it's better to know it is going in than discover it 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.
If the trial import looks messy, is that what we'll actually end up with?#
No, and this is probably the single most important thing to understand before testing anything yourself. A trial or raw import 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.
Judge the destination, not the raw import.
Is there a plugin that converts our MadCap Flare content automatically, or do we have to export everything page by page?#
There's no one-click plugin - migration is a structured, assisted process, not an automatic conversion. You export your content (as HTML, Markdown, or a Flare project file), and the migration team works through translating structure, formatting, and reuse logic into the new platform. It's more hands-on than a plugin, but that's also why single-sourcing elements can be rebuilt properly instead of just dumped in broken.
What happens if something doesn't work partway through - and can we still go back?#
You're handing over years of documentation and hoping it comes out right, especially if you've never been through a migration like this before. In practice, this is exactly what the validation phase is for: nothing goes live without your team reviewing it first, and any issues get raised and fixed before go-live, not discovered after the fact. Onboarding support is dedicated to your migration specifically, and that same relationship continues after go-live, so if something surfaces weeks later, you're not starting over with someone new.
Can we rename things like notes, tips, and warnings to match how we already label them?#
Not through the interface directly, but yes in practice - this is handled through custom CSS (and in some cases light custom JavaScript for writer-facing labels, like changing what a callout says on hover). If your team already has a consistent style - for instance, everything green is an "example," everything blue is a "note" - that convention can usually be preserved, either through custom styling or by setting up a reusable content block your writers use going forward. If your styling is heavily customized in Flare, it's worth treating as its own conversation rather than assuming it transfers as-is.
What happens to edits my team makes while migration is in progress?#
This is one of the more overlooked questions, and a fair one to ask early. Since migration happens space by space rather than all at once, there's a period where some content lives in the new system and some is still being worked on in the old one. The practical answer is to agree on a cutoff point with the migration team before you start - content changes made after that point in the old tool need to be manually reflected in the new one, since they won't sync automatically. Flagging this at the start of the process avoids surprises partway through.
Will our documentation URLs keep working after we go live?#
Yes - this is one of the things handled specifically at cutover. Production URLs can be preserved through custom URL settings, so links your customers have bookmarked, or that partners have linked to, keep working rather than breaking when you switch over.
Do our existing spaces or products need to become separate, disconnected sites, or can they work together?#
They can work together. Multiple existing sites, product lines, or portals get consolidated into a clearer structure - organized as spaces, products, or audiences - as part of migration, rather than recreated as separate disconnected sites in the new tool. This is usually worked through directly with your team early on, since the right structure depends on how your products and audiences are actually organized, and it's easier to agree on space names and structure before content starts moving over than to reorganize afterward.
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 own content, but the shape of the process stays the same: start small, validate before scaling, rebuild single-sourcing properly, and cut over without losing what your team already relies on.
The most useful 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 - not with a full commitment, but with a clear look at your own content and what moving it would involve, before deciding anything else.