There is no native Confluence-to-Google-Workspace path. Every method requires extracting content via API or export, transforming macros to static equivalents, and rebuilding the page hierarchy as Drive folders.
A technical guide covering every method to migrate Confluence to Google Workspace — API rate limits, macro handling, data mapping, and the edge cases that break migrations at scale.
Read this first
Pair-specific gotchas that catch teams out. Each one has cost somebody a weekend.
If your target is new Google Sites, assume manual or semi-manual rebuilds
Google's Sites API only supports classic Sites, is deprecated, and cannot access the rebuilt Sites launched in 2016. (developers.google.com)
The Native Export Trap
Data looks migrated but is not actually usable. Broken inline references, missing blog posts, and manual ACL work create a cleanup burden that can exceed the effort of a proper API migration.
API token-based Confluence traffic is still governed by burst rate limits, separate from
API token-based Confluence traffic is still governed by burst rate limits, separate from the new points-based system. If you're running migration scripts with API tokens, you'll hit both limits independently. The v2 API also requires a separate request per page for children, properties, and attachments — the expand parameter from v1 is not available. This N+1 request pattern amplifies your rate limit consumption significantly.
As a general rule
any Confluence macro that pulls live data from an external system (Jira, Trello, database) or references other Confluence pages dynamically will become static text after migration. Plan your content review around this reality.
Atlassian's rate limits are aggressive for bulk extraction
The points-based quota resets at the top of each UTC hour. A migration script that starts at 12:50 UTC may exhaust its quota in 10 minutes and sit idle for 50 minutes. Schedule batch jobs to start at the top of the hour. The v2 API's N+1 request pattern (separate calls for children, properties, and attachments per page) amplifies consumption quickly.
Google Drive does not support pre-generated IDs when creating Google Docs or requesting
Google Drive does not support pre-generated IDs when creating Google Docs or requesting conversion to Docs format. Internal link rewriting must happen as a second pass after all target documents exist. Drive batch requests can reduce round trips for metadata operations, but not for media upload, download, or export. Concurrent permission operations on the same file are also not supported — only the last update is applied. (developers.google.com)
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 Confluence
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 Google Workspace 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 Google Workspace 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 Google Workspace models that. Then confirm how many locales you have and whether translation relationships between articles survive the move.
-
Document count comparison
Total pages in Confluence vs. total Docs in Google Drive. Account for intentionally excluded content (archived spaces, stale pages).
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 Confluence 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.
Confluence → Google Workspace specifics
- Permission audit
- For each migrated Space, verify that the Shared Drive members match the original Confluence Space permissions.
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 Google Workspace lets you set on import versus which it computes — computed dates are a common surprise.
Schema Mapper Opens pre-loaded with the Confluence → Google Workspace 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 Google Workspace'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 — Google Workspace, 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 Google Workspace's importer expects -
Plan localisation and freeze the spec
Confirm how translated articles link to their source language in Google Workspace, then version and sign off the mapping spec.
-
Convert HTML elements to Google Docs API requests
The Google Docs API uses batchUpdate with structured request objects (InsertText, InsertInlineImage, UpdateTextStyle, etc.), not HTML. You cannot send raw HTML to the Docs API; every element must become a JSON command.
CSV to JSON Converter Turn flat exports into the JSON the API expects -
Handle inline attachments
Images referenced as <ac:image> with <ri:attachment> must be downloaded from Confluence and uploaded to Drive, then linked in the new Doc at the correct insertion point.
-
Map users
Replace Atlassian account IDs in @mentions and comments with Google Workspace email addresses.
Confluence → Google Workspace specifics
- Parse Confluence Storage Format XHTML
- Use an HTML parser (e.g., BeautifulSoup, Cheerio) to walk the DOM.
- Replace macros with static equivalents
- Detect <ac:structured-macro> elements, extract parameters, and generate the appropriate static replacement (text, image, hyperlink, or Smart Chip).
- Queue internal links for second-pass rewriting
- Build a lookup map of {confluence_page_id: google_doc_id} and rewrite all <a> tags pointing to Confluence URLs after all Docs are created.
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 Google Workspace 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.
Confluence → Google Workspace specifics
- Attachment count and size
- Compare total attachment count and aggregate file size between source and target.
- Internal link integrity
- Sample 10% of Docs and verify that internal links resolve to the correct target Doc, not a dead URL or an atlassian.net address.
- Formatting spot-check
- Visually compare 5–10 complex pages (those with tables, images, code blocks, multi-column layouts) against their Confluence originals.
- User Acceptance Testing (UAT)
- Have content owners from each team verify their migrated Spaces. They'll catch organizational issues that automated checks miss.
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 Google Workspace 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 Google Workspace, 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 Confluence, 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 Confluence and Google Workspace 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 Confluence available read-only until traffic has recovered, take a final export, and only then close the account.
-
Rebuild document workflows
Confluence page approvals, watch notifications, and automation rules don't carry over. Recreate them using Google Workspace tools (Drive activity notifications, Apps Script automations).
-
Monitor access issues
Permission mapping errors often surface days after migration when someone who should have access tries to open a Doc. Set up a dedicated support channel for the first two weeks.
-
Archive or delete Confluence
Once UAT is complete and the read-only fallback period has passed, export a final Confluence backup and decommission the instance.
Data Profiler Prove field completeness held up through the load
Confluence → Google Workspace specifics
- Jira Issue Macro
- Renders live Jira ticket data. Best conversion: extract the ticket key and summary, rewrite as a static hyperlink to the Jira URL, or use a Google Docs Smart Chip if the URL resolves.
- draw.io / Gliffy Diagrams
- Embedded interactive diagrams. Confluence stores these as attached .xml and .png files. Export as PNG/SVG and insert as static images. Editability is lost.
- Table of Contents Macro
- Auto-generated TOC from headings. Google Docs has a built-in TOC feature, but it must be inserted separately — it won't auto-generate during API import.
- Page Properties / Page Properties Report
- Structured metadata extraction across pages. No equivalent in Google Docs. Convert to a static table or move the workflow to a linked Google Sheet.
- Expand/Collapse Macro
- Toggleable content sections. Google Docs has no collapsible sections. Content must be flattened into standard headings and paragraphs.
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
What breaks
Known failure modes. Have a recovery plan for each before you cut over.
Jira Issue Macro
— Renders live Jira ticket data. Best conversion: extract the ticket key and summary, rewrite as a static hyperlink to the Jira URL, or use a Google Docs Smart Chip if the URL resolves.
draw.io / Gliffy Diagrams
— Embedded interactive diagrams. Confluence stores these as attached .xml and .png files. Export as PNG/SVG and insert as static images. Editability is lost.
Table of Contents Macro
— Auto-generated TOC from headings. Google Docs has a built-in TOC feature, but it must be inserted separately — it won't auto-generate during API import.
Page Properties / Page Properties Report
— Structured metadata extraction across pages. No equivalent in Google Docs. Convert to a static table or move the workflow to a linked Google Sheet.
Expand/Collapse Macro
— Toggleable content sections. Google Docs has no collapsible sections. Content must be flattened into standard headings and paragraphs.
Code Block Macro
— Syntax-highlighted code. Google Docs has no native code formatting. Use monospace font or link to a separate code file.
Include Page / Excerpt Include
— Content pulled dynamically from other pages. Must be resolved to static content at migration time; the live relationship is permanently severed.
Deeply nested hierarchies
— Confluence allows unlimited page nesting. Google Shared Drives cap at 100 folder levels. If your Confluence tree exceeds this, you need to flatten intermediate levels — which breaks the organizational logic users expect. Design your flattening strategy before you start loading.
Inline attachments vs. block attachments
— Confluence distinguishes between images embedded in page body (<ac:image>) and files attached to the page but not embedded. Inline images must be inserted at the correct document position via the Docs API; block attachments go to the parent folder in Drive. Both need different handling.
Cross-space links
— Pages linking to content in other Spaces require the target Space to be migrated first, or links must be queued for a second-pass rewrite after all Spaces are loaded.
User identity mapping
— Confluence uses Atlassian Account IDs (UUIDs). Google uses email addresses. If users don't have matching emails, permissions and comment attribution break silently. Resolve the mapping before you start loading. (support.atlassian.com)
API throttling under load
— Confluence's points-based quota resets at the top of each UTC hour. A migration that starts at 12:50 UTC may exhaust its quota in 10 minutes and sit idle for 50. On Google's side, exceeding the per-second write limit triggers 403/429 errors that require backoff.
Large attachments
— Confluence allows large file attachments but stops indexing content beyond 100 MB. Google Drive allows files up to 5 TB, but the 750 GB/day upload cap means a space with 800 GB of attachments takes two calendar days minimum.
Permission inheritance on move
— Avoid staging content in My Drive and moving it into Shared Drives later. Google notes that inherited folder permissions are not copied when a child folder is moved into a Shared Drive. Create content directly in the target Shared Drive. (developers.google.com)
Comments and mentions
— Drive comments can be recreated, including anchored comments, but exact positions can drift after content conversion. Preserve author and timestamp in the comment body if exact anchors can't be recreated. (developers.google.com)
Tools used in this playbook
All free, all run entirely in your browser — nothing is uploaded.
FAQ
Is there a native Confluence to Google Workspace migration tool?
No. Google Workspace Migrate does not list Confluence as a supported source. Teams must use Confluence exports, the Confluence REST API, third-party tools, or a managed migration service. Native HTML exports break attachment paths and exclude blog posts; Word exports are incompatible with Google Docs.
What happens to Confluence macros when migrating to Google Docs?
All dynamic macros (Jira issue links, draw.io diagrams, Table of Contents, Include Page, Expand/Collapse, Code Block) must be converted to static content. Google Docs has no macro system. Jira links become static text with hyperlinks, diagrams become PNG images, and dynamic includes are resolved to inline text at migration time.
What are the API rate limits for Confluence and Google Drive during migration?
Confluence Cloud enforces a points-based quota of 65,000 points per hour (default Global Pool) as of March 2, 2026, resetting at the top of each UTC hour. Google Drive API limits sustained writes to 3 requests per second per account, with a 750 GB/day upload cap. Both return 429 errors when exceeded.
How do Confluence page permissions map to Google Drive?
Confluence supports Space-level permissions and independent page-level restrictions. Google Drive inherits permissions from parent folders by default. To replicate page-level restrictions, use Google Drive's limited-access folder feature to restrict visibility to specific members within a Shared Drive. Exact parity is not always possible.
How long does a Confluence to Google Workspace migration take?
A small space under 100 pages can be done manually in a day. An API-based migration of 100–5,000 pages typically takes 2–6 weeks of engineering. Enterprise migrations with macro conversion, permission mapping, and delta runs take 4–12 weeks in-house, or can be completed in days with a managed service like ClonePartner.