No native migration path exists. Every article must be converted to Confluence Storage Format, with separate pipelines for attachments and link rewriting.
There is no native, one-click migration path from Document360 to Confluence. Document360 exports articles as .md, .html, or .json depending on editor type and language — Confluence rejects all three formats natively. Confluence requires content in its proprietary Storage Format (XHTML with custom ac: and ri: macro elements) or Atlassian Document Format (ADF). A single unclosed tag or unescaped ampersand causes rejection of the entire page payload. The real work is format conversion, media handling, and internal link rewriting — with separate pipelines for Markdown-editor and WYSIWYG-editor articles, all constrained by rate limits on both sides.
Read this first
Pair-specific gotchas that catch teams out. Each one has cost somebody a weekend.
Do not confuse Confluence's two import flows
The older document importer handles Word, Google Docs, and OneDrive files in batches of up to 30 files and 50 MB total. The newer HTML importer is a separate flow that creates a new space from a ZIP of HTML files. They have different limits and different behavior. (support.atlassian.com)
Approach for building the converter
Parse Markdown to an AST using a library like markdown-it (JavaScript) or mistune (Python), then write a custom renderer that outputs Confluence Storage Format XML instead of standard HTML. For HTML source content, use an HTML parser like BeautifulSoup (Python) or cheerio (JavaScript) to walk the DOM and emit the corresponding Confluence macro elements. This two-track approach — one renderer for Markdown, one transformer for HTML — matches Document360's mixed-editor reality.
Document360's native project export explicitly excludes content reuse elements
Templates, variables, snippets, and glossary terms are not part of the export/import process and must be recreated manually. (docs.document360.com)
WebHelp export is already lossy
Document360's HTML5 WebHelp export includes search, media support, and internal links, which makes it look like a good Confluence import source. But WebHelp excludes attachments, glossary definitions, inline comments, breadcrumbs, article-level table of contents, and previous/next navigation. If attachments or glossary content matter, WebHelp is not a full-fidelity source. (docs.document360.com)
Before starting a migration, make a few test calls and check the X-RateLimit-Remaining
Before starting a migration, make a few test calls and check the X-RateLimit-Remaining header to determine your actual quota. If you are migrating hundreds of articles via API on a Professional or Business plan, you may need to batch your calls across multiple reset windows.
If you use the native HTML importer instead of the API, your limiting factor may be
If you use the native HTML importer instead of the API, your limiting factor may be Confluence's attachment size setting, not a published HTML-import cap. Atlassian's FAQ tells admins to increase the attachment-size limit so it exceeds the HTML ZIP size before import. (support.atlassian.com)
Common failure mode
DIY scripts that attempt a single-pass migration end up with broken internal links on every page that references another page created later in the sequence. Always plan for a two-pass approach or use a migration engine that handles deferred link resolution.
Pilot with the hard cases first, not the easy ones
Pick pages with code blocks, tables, nested lists, inline images, multilingual content, and repeated titles. If you imported into a staging space, Confluence says moved items carry their attachments, comments, child items, and incoming links, and get automatic redirects. That makes staging-space validation much safer than importing directly into production. (support.atlassian.com)
Store the original Document360 article ID, category ID, URL, and last-modified date as
Store the original Document360 article ID, category ID, URL, and last-modified date as Confluence page properties. This gives you idempotent reruns, easier QA, and a clean redirect map. (apidocs.document360.com)
Always migrate into a staging space first, not your production space
Validate in staging, then either move pages to the production space or rename the staging space. This gives you a clean rollback path without risking production content.
The runbook
Work top to bottom. Tick steps as you go — your progress is saved in this browser.
01 Discovery Decide what content deserves to move before you plan how to move it.
Objective A content inventory with a keep/rewrite/retire decision on every article and an agreed URL strategy.
Keep these open
-
Inventory all content in Document360
Count articles, categories, attachments, images and embedded media, and pull page views and last-updated dates for each article. Usage data is what makes the next decision defensible rather than political.
Data Profiler Get real record counts instead of estimating from memory -
Make a keep, rewrite or retire call on every article
Most knowledge bases are half stale. Migrating everything imports the staleness and doubles the work; use views and last-updated to triage, and get the owning team to confirm. This usually removes 30-50% of scope.
Migrating stale content is the most common knowledge-base migration mistake — it costs effort and actively degrades the new site.
-
Agree the URL and redirect strategy
Decide the Confluence URL structure and whether you can serve 301 redirects from the old paths. Public help centres carry real search traffic and inbound links; losing it is a measurable commercial impact.
Without 301 redirects from old article URLs you lose accumulated search ranking and every external link and bookmark breaks.
-
Map the information architecture
Document the current category tree and design the target one, checking whether Confluence supports your nesting depth. Deeply nested hierarchies frequently have to be flattened, which changes navigation for everyone.
-
Confirm permissions, audiences and localisation scope
Establish which content is public, internal or restricted, and how Confluence models that. Then confirm how many locales you have and whether translation relationships between articles survive the move.
Document360 → Confluence specifics
- Medium (200–1,000 articles, mixed editors)
- 2–3 weeks. Requires custom parser adjustments for edge cases like complex tables or nested macros.
- Large/Complex (1,000+ articles, multilingual, heavy media)
- 3–4 weeks. Rate limits dictate the transfer speed, and link rewriting requires multiple passes.
Don't move on until
- Full content inventory with page views and last-updated dates
- Keep / rewrite / retire decision recorded per article
- URL and redirect strategy agreed with whoever owns SEO
02 Data Audit Audit the markup, the links and the assets — that is where KB migrations break.
Objective A content export with markup, internal links and every embedded asset accounted for.
Keep these open
-
Export content and assess markup fidelity
Export articles in the richest format available and inspect what survived: tables, code blocks, callouts, nested lists, anchors and embedded video. Rich formatting is where fidelity is lost, and it is lost quietly.
HTML-to-Markdown conversion routinely mangles nested lists, tables and code blocks. Inspect the output rather than trusting the converter.
Data Profiler Profile the Document360 export for nulls, outliers and type drift -
Inventory every internal link and cross-reference
Extract all internal links, anchor links and article cross-references. These break by default: the target URL structure differs, so every internal link needs rewriting as part of the load, not afterwards.
Internal links left pointing at old URLs turn the new knowledge base into a maze of 404s on day one.
-
Inventory images, attachments and embedded media
List every asset with its URL, size and type, and confirm each still resolves. Assets hosted on the old platform's CDN will 404 the moment you decommission it, so they must be rehosted, not referenced.
Images referenced from the source platform's CDN break when the old account closes. Download and rehost every asset.
-
Find and fix broken links and orphans
Crawl for existing broken internal and external links, and find articles no category links to. Fix them before migrating — a migration is a bad time to discover pre-existing rot.
-
Check for PII and internal information in public content
Scan for customer names, internal hostnames, credentials in code samples and screenshots containing real data. Republishing these on a public help centre is a disclosure, and screenshots are the usual culprit.
PII & Compliance Scanner Find regulated fields before they land in a new system -
Normalise metadata
Standardise authors, tags, timestamps to UTC, and locale codes. Author mapping needs a decision for people who have left — attribution to a deleted user usually fails the import.
-
Delete the entire space
If you created a dedicated Confluence space for the migration, the simplest rollback is to delete the space and start over. Use DELETE /wiki/rest/api/space/{spaceKey} — this removes all pages, attachments, and metadata in that space. This is destructive and irreversible.
-
Delete individual pages
If you need to roll back selectively, use DELETE /wiki/rest/api/content/{pageId} for each page. Deleting a parent page moves child pages to the trash as well.
-
Use the migration log
Your migration script should log every created page ID. On rollback, iterate through the log and delete in reverse order (children before parents).
Document360 → Confluence specifics
- Multilingual projects
- export as .json (all languages bundled per article)
- Burst limits
- Per-second rate limits apply per endpoint, independent of any hourly quota. Sending too many requests per second triggers HTTP 429 even if you have quota remaining.
- Body expansion cap
- API queries that expand body.storage are limited to 50 results per request.
- Page body size
- Content bodies exceeding roughly 64 KB can trigger HTTP 400 errors.
- 429 response handling
- The Retry-After header tells you how many seconds to wait. Implement exponential backoff with jitter — do not just retry immediately.
Don't move on until
- Content exported with markup fidelity assessed
- Every internal link and asset reference inventoried
- Broken links and missing assets fixed or logged
03 Field Mapping Map structure, metadata, permissions and — above all — URLs.
Objective A mapping covering article fields, taxonomy, permissions and a complete old-to-new URL map.
Keep these open
-
Map the article schema
Map title, body, excerpt, author, dates, status, tags, SEO metadata and any custom properties. Confirm which fields Confluence lets you set on import versus which it computes — computed dates are a common surprise.
Schema Mapper Opens pre-loaded with the Document360 → Confluence field pair -
Map the taxonomy and hierarchy
Map categories, sections and tags to the target structure, resolving any nesting-depth limit explicitly. If you must flatten, decide how the lost level is preserved — usually as a tag or a title prefix.
JSON to CSV Converter Flatten nested API responses into a reviewable sheet -
Map permissions and audience segmentation
Map public, logged-in, and role-restricted visibility to Confluence's model. Verify the mapping deliberately: internal content accidentally published publicly is the highest-severity failure in this whole category.
Permission mapping errors publish internal documentation to the open web. Verify visibility on every restricted article after load.
-
Build the complete old-to-new URL map
Produce a row per article mapping the old URL to the new one, then confirm exactly where the 301s will be served — Confluence, a CDN, or your own web layer. Without this artifact the redirect step cannot be executed at all.
-
Define the markup conversion and link-rewrite rules
Specify how each markup construct converts and how internal links are rewritten using the URL map. Write it as a repeatable transform, not manual edits — you will run it more than once.
Data Format Converter Reshape the export into the format Confluence's importer expects -
Plan localisation and freeze the spec
Confirm how translated articles link to their source language in Confluence, then version and sign off the mapping spec.
Document360 → Confluence specifics
- Transform
- Convert Markdown/HTML to Confluence Storage Format (or ADF), rewrite internal links, rename duplicate titles, and map the category hierarchy to a Confluence page tree.
Don't move on until
- Article schema and taxonomy mapped
- Permission and audience model mapped to target equivalents
- Complete URL map produced and redirect method confirmed
04 Test Migration Pilot the hardest articles, then read them.
Objective A pilot load whose formatting, links, assets and search all hold up under human review.
Keep these open
-
Configure Confluence with the agreed structure
Create the category tree, permission groups, locales and branding before loading. Articles loaded before their categories exist land uncategorised and have to be moved by hand.
-
Pick the most difficult articles as the pilot
Choose 20-50 articles for difficulty: the longest, the most heavily formatted, ones with tables and code blocks, deep internal linking, many images, embedded video, restricted visibility, and non-Latin scripts. Easy articles prove nothing.
-
Run the conversion and load with link rewriting
Apply the markup conversion, rewrite internal links from the URL map, upload and re-reference assets, then load. Log every conversion warning rather than suppressing it.
-
Read every pilot article side by side
Open source and target together and compare rendering. This step is manual on purpose: no automated check catches a table that collapsed into a paragraph or a code block that lost its indentation.
-
Click every link and load every asset
Verify each internal link resolves, each image loads from the new host, each attachment downloads and each embed plays. Assets still served from the old CDN are the defect that surfaces only after decommissioning.
Migration Validation Tool Diff the pilot batch against source before scaling up -
Test search and permissions
Search for known terms and confirm the right articles rank, then verify every restricted pilot article is invisible to an anonymous browser. Test permissions from a logged-out session, not an admin one.
Document360 → Confluence specifics
- Sample size
- Migrate at least 10% of your total articles, with a minimum of 20 pages.
- Stratified selection
- Include articles from each editor type (Markdown, WYSIWYG, Advanced WYSIWYG), each depth level of your category tree, and each language if multilingual.
- Prioritize hard cases
- Include at least 2–3 pages with each of these: complex tables, code blocks with multiple languages, inline images, internal cross-links, callout boxes, and duplicate titles.
Don't move on until
- Complex articles render correctly with formatting intact
- Every internal link and asset in the pilot resolves
- Search returns sensible results for the pilot content
05 Cutover Publish, redirect, and keep the search traffic.
Objective All in-scope content live in Confluence with redirects serving and search engines informed.
Keep these open
-
Load the full content set ahead of the switch
Run the full conversion and load into Confluence, unpublished or on a staging domain. Content migration differs from data migration here: you can stage the whole thing before anyone sees it.
-
Publish the runbook with the redirect step first-class
Sequence the freeze, final delta, publish, redirect activation, sitemap submission and link updates, with owners for each. Redirect activation is the step with lasting commercial consequences, so it gets explicit ownership.
-
Freeze editing and migrate the delta
Stop editing in Document360, then convert and load anything changed since the full load. Announce the freeze to every team that publishes — content teams are used to editing whenever they like.
-
Publish and verify permissions live
Publish the content set, then immediately verify restricted articles are not publicly reachable using an anonymous session. Do this before announcing the new site, not after.
Verify restricted content from a logged-out browser. An admin session will show you everything and tell you nothing.
Migration Validation Tool Confirm the final delta landed before you reopen -
Activate 301 redirects and submit the sitemap
Turn on the redirects from the URL map, then spot-check a sample of high-traffic old URLs and confirm each returns 301 to the right article. Submit the new sitemap and keep the old one reachable until search engines have recrawled.
Redirect chains and redirect loops both leak ranking. Verify each redirect resolves in a single hop.
-
Repoint in-product and support links
Update help links embedded in your product, in support macros, in email templates and in onboarding material. These are the links your existing customers actually use, and they are easy to forget.
Don't move on until
- All content loaded, categorised and correctly permissioned
- 301 redirects live and verified from a sample of old URLs
- Sitemap submitted and support links repointed
06 Validation Watch traffic, links and search rankings for weeks, not hours.
Objective Verified content completeness, healthy redirects, and search traffic recovered to baseline.
Keep these open
-
Reconcile content counts and assets
Compare article counts by category and status, plus asset counts, against source. Confirm every article in the keep list is present and every retired one genuinely is not.
Migration Validation Tool Reconcile Document360 and Confluence record-for-record -
Crawl the new site for broken links and assets
Run a full crawl for 404s, broken images and missing attachments, and fix everything it finds. Repeat the crawl after the fixes rather than assuming they worked.
-
Verify the redirects at scale
Test every mapped old URL for a single-hop 301 to the right destination. Chains and loops both leak ranking and are invisible unless you check the whole map, not a sample.
-
Monitor organic traffic and rankings for four to eight weeks
Track organic sessions, impressions and rankings for your top articles against baseline. A dip in the first two weeks is normal; one that has not recovered by week six is a redirect or indexing problem to investigate.
Do not decommission the old platform until search traffic has recovered — you may still need the old URLs to diagnose a ranking loss.
-
Verify search, permissions and feedback loops
Confirm on-site search returns good results for real queries, re-verify restricted content from a logged-out session, and check article feedback and analytics are collecting.
-
Sign off and decommission on a delay
Get acceptance against the Discovery criteria, keep Document360 available read-only until traffic has recovered, take a final export, and only then close the account.
Document360 → Confluence specifics
- Reverse proxy or CDN rules
- If your Document360 instance was on a custom domain, configure your reverse proxy (e.g., Nginx, Cloudflare) to 301-redirect old URL paths to the corresponding Confluence page URLs.
- Document360 custom domain settings
- If you control the DNS for your documentation domain, point it to a redirect service that maps old slugs to new Confluence URLs using the mapping table you built during migration.
- Redirect map file
- During migration, generate a CSV mapping every old Document360 URL to the new Confluence URL. This file feeds whatever redirect mechanism you choose.
Don't move on until
- Article counts reconciled and no broken links remain
- Redirects returning 301 with no chains or loops
- Organic traffic recovered to within tolerance of baseline
Field mapping reference
The field-by-field mapping for each object. Use this as the starting point for your mapping spec.
Object Migration Path
| Document360 field | Confluence field | Notes |
|---|---|---|
| Articles (body content) | API or ZIP export | Content must be converted to Storage Format or ADF |
| Categories & subcategories | API or ZIP export | Hierarchy preserved in the ZIP's folder structure and JSON manifest |
| Media files (images, PDFs) | ZIP export includes a Media folder | Must be re-uploaded as Confluence attachments via API |
| Article metadata (title, slug, order, status) | API only | ZIP includes order and status; API provides richer metadata |
| Article versioning | API only (per-version retrieval) | Confluence stores versions natively, but you must create them sequentially |
| Multilingual content | API or ZIP export (per-language) | Each language must be handled as a separate migration pass |
Architecture Confluence Architecture
| Document360 field | Confluence field | Notes |
|---|---|---|
| Project | Confluence Site | 1:1 — each D360 project maps to a Confluence Cloud site |
| Workspace | Space | Each workspace becomes its own Confluence Space with a unique space key |
| Top-level Category | Parent Page (under Space homepage) | Categories become pages that serve as containers — add overview text or they appear blank |
| Subcategory | Child Page (nested under parent) | Confluence supports deep nesting; mirror D360's category depth |
| Article | Page (child of its category page) | Body converted to Storage Format; title preserved |
| Article order | Page order within parent | Set via the Confluence API's position parameter on v2 endpoints |
| Media file | Attachment on the page that references it | Or attach to a shared "assets" page if media is reused across articles |
| Article slug | Page title (URL auto-generated) | Confluence auto-generates URLs from titles; no custom slug support |
| Tags | Labels | Document360 tags map to Confluence labels; apply via POST /wiki/rest/api/content/{id}/label |
| Custom fields | Page Properties or Labels | Use the Page Properties macro for structured metadata that can be queried with the Page Properties Report macro |
| Content Snippets | Page Templates or Include Page macro | Snippets lose their reuse structure on export; recreate as Confluence page templates or use {include} macros referencing shared pages |
| Users / Teams | Confluence Users / Groups | No automatic mapping; provision users in Confluence separately and assign space/page permissions |
Risk matrix
Per-object risk for this pair. Plan extra validation around anything marked high.
| Object | Risk | Notes |
|---|---|---|
| Internal Links | high | All slug-based URLs break — require two-pass rewriting to ac:link elements |
| Code Blocks | high | Must be wrapped in ac:structured-macro CDATA blocks — standard backticks fail |
| Templates & Variables | high | Excluded from export entirely — must be recreated manually in Confluence |
| Snippets & Glossary | high | Content reuse elements are not exported and have no direct Confluence equivalent |
| Inline Images | medium | Require download, upload as attachment, and ac:image macro reference update |
| Duplicate Titles | medium | Confluence rejects pages with identical titles within a Space |
| Mixed Editor Types | medium | Parser must detect and branch on Markdown, WYSIWYG, and Advanced WYSIWYG content |
| RTL Content | medium | Document360 supports per-article RTL — Confluence handles RTL via language settings only |
| Article Analytics | low | Views, ratings, and feedback are platform-specific and not exportable |
| Simple Text Content | low | Headings and paragraphs convert to Storage Format cleanly |
The hard parts
What makes this specific migration difficult, beyond the mechanics.
Format Conversion
Every article must be converted to Confluence Storage Format XHTML with custom ac: and ri: macro elements. Standard HTML is rejected.
Mixed Editor Types
A single project can contain Markdown, HTML, and JSON files from different editors, requiring separate parsing pipelines.
Title Collisions
Confluence enforces unique page titles per Space. Document360 allows duplicate names across categories, requiring deterministic renames.
Media Pipeline
Images must be uploaded as Confluence attachments via a page-ID-dependent workflow and referenced with ac:image macros.
Link Rewriting
Document360 article slugs must be mapped to Confluence page titles and rewritten using ac:link Storage Format syntax.
What breaks
Known failure modes. Have a recovery plan for each before you cut over.
Mixed editor types in a single project
Single-language exports can contain both .md and .html files. Multilingual exports become .json. One parser will not cover every scenario — your converter must detect the editor type and branch accordingly. (docs.document360.com)
Variables and snippets rendered inline
With isForDisplay=true, variables and snippets resolve into the content body. You get the rendered version, but you lose the reuse structure. With isForDisplay=false, you get raw tokens that will not render in Confluence. There is no option that preserves both fidelity and reuse.
Confluence page title uniqueness
Within a single Space, all page titles must be unique. Duplicate "Overview" or "Introduction" pages from different Document360 categories will collide.
Right-to-left (RTL) content
Document360 supports per-article RTL settings. Confluence handles RTL via language settings, not per-page toggles. RTL articles may need manual styling adjustments post-migration.
64 KB page body limit
Very long Document360 articles with base64-encoded inline images can exceed this limit on the Confluence API. Convert base64 images to attachments before pushing the page body.
Category pages with content
Document360 categories can have their own body content. In Confluence, the equivalent parent pages must also have body content set — do not skip category descriptions or you will have blank container pages.
HTML import degradation
If using Confluence's native HTML importer, code blocks become plain text, iframe elements are unsupported, equations downgrade to plain text, and embedded videos become hyperlinks. (support.atlassian.com)
Metadata gaps
Document360 exposes workflow status, custom fields, translation status, and public/private visibility via API. Confluence can store some of these as page properties, labels, or restrictions, but it requires an explicit mapping plan. Nothing carries over automatically. (apidocs.document360.com)
Tools used in this playbook
All free, all run entirely in your browser — nothing is uploaded.
FAQ
How much downtime is required?
Zero. Migrating Document360 to Confluence is a non-destructive read operation on the source side. Your existing documentation remains live until you update your DNS or internal links to point to Confluence.
How do you validate the migration?
We run automated validation scripts that compare the total article count, attachment count per page, and link integrity between Document360 and Confluence. We also spot-check complex formatting like tables and code blocks.
How long does the migration take?
Most migrations complete in 2 to 4 weeks. The exact timeline depends on your article count, media volume, and Document360 API rate limits.
What happens if the migration fails partway through?
If you migrate into a staging space (which we recommend), you can delete the space and re-run from scratch. Your migration script should log every created page ID so you can roll back selectively if needed. The source Document360 instance is never modified during migration.
Does this work for Confluence Data Center, or only Cloud?
The extraction and transformation steps are the same. The loading step differs — Data Center supports XML site imports and uses different authentication methods. The Storage Format itself is compatible across Cloud and Data Center.