Slab's native Confluence importer handles simple spaces but drops macros and takes 1–3 days. For complex migrations, use an API pipeline or managed service to preserve links, attachments, and content fidelity.
Slab has a native Confluence importer — you upload a Confluence XML space backup, Slab processes it server-side, and you get a confirmation email 1–3 days later. But macros, page-level permissions, version history, and embedded content without a Slab equivalent are silently dropped. For small, mostly-text Confluence spaces, the native importer works. For anything with complex macros, deep page trees, or hundreds of attachments, you need either a custom API pipeline or a managed migration service. Confluence is built on Spaces with strict parent-child page hierarchies, XHTML-based storage format with embedded macros, and granular page-level restrictions. Slab is built on Topics (flexible groupings) and Posts stored in Quill Delta format — with no macro system, no page templates, no per-post permissions, and a flatter organizational model. The macro problem is the biggest architectural gap: Jira macros, status badges, draw.io diagrams, and expand/collapse have no Slab equivalent. A successful migration requires converting Confluence Storage Format to Markdown, handling every macro type explicitly, re-hosting attachments from Confluence's CDN, rewriting all internal links via a two-pass page-ID-to-post-URL mapping, and navigating Slab's 1,000 complexity points per minute GraphQL API rate limit — all while Confluence's own API enforces separate burst and point-based quotas.
Read this first
Pair-specific gotchas that catch teams out. Each one has cost somebody a weekend.
Confluence exports only include published content
Every native export format — XML, HTML, PDF — captures only the published version of each page. Unpublished draft changes are silently excluded. There is no way to export unpublished drafts through the Confluence UI. Audit your spaces before starting.
The macro problem is the biggest architectural gap
If your Confluence pages are heavily macro-dependent (Jira issue tables, status macros, roadmap macros, draw.io diagrams), expect significant manual rework post-migration. No automated tool can translate a Jira macro into a Slab equivalent because the equivalent doesn't exist. Plan for this during scoping, not after cutover.
XML export size limits
Confluence Cloud has historically enforced size limits on XML space exports. Large spaces with heavy attachments routinely exceed these. If your export fails, try exporting without attachments first, then migrate attachments separately via API. Atlassian's own documentation recommends against XML exports as a primary backup strategy for large instances.
Minimize query complexity
Only request the fields you need per query. Split extraction into phases: structure and IDs first, content second, metadata third. Fetching everything in one deeply nested query will burn through your 1,000-point budget in a few requests. Slab's help center does not spell out the rate-limit model as explicitly as Atlassian does, so validate throughput assumptions against your own workspace before committing to a migration schedule.
Service-account access audit
On Slab, API visibility follows the Slab Bot user's permissions. On Confluence, exported content depends on what the exporting user can see. Before you migrate, make sure your migration identities can actually see every space, page, and restricted topic in scope. (help.slab.com)
This is a skeleton, not production code. A real migration script needs
exponential backoff with jitter, comprehensive error logging, a persistent mapping table (database, not in-memory), attachment download and re-upload handling, content transformation for every macro type, idempotent writes, and a separate link-rewriting pass. Confirm actual query and mutation names against the schema exposed from Slab's Developer settings. Budget 2–4 weeks for a senior engineer to build, test, and validate.
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 Slab 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 Slab 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 Slab models that. Then confirm how many locales you have and whether translation relationships between articles survive the move.
Confluence → Slab specifics
- Confluence's macro debt
- Years of third-party macros, Jira macros, and custom templates create pages that are more macro scaffold than content. When half your pages depend on plugins to render, the editing experience degrades. Slab's clean editor is the antidote.
- Cost consolidation
- Confluence Cloud pricing scales per user, and once you add Atlassian Guard (formerly Access) for SSO and security controls, costs compound. Slab's per-user pricing is typically lower for teams that only need a knowledge base — not the full Atlassian suite.
- Simplicity over configurability
- Slab is intentionally opinionated: a clean editor, fast unified search, and a flat learning curve. For teams that don't need Confluence's deep Jira integration, the complexity is overhead.
- Search quality
- Slab's unified search indexes content across integrated tools (Slack, GitHub, Google Drive). Confluence's built-in search has been a persistent complaint in the Atlassian community, particularly for large instances.
- Week 2: Sample Migration
- Move 2–3 complex spaces to validate formatting and link rewriting.
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 → Slab specifics
- Week 1: Audit & Mapping
- Identify macro debt, map permissions, and define the topic hierarchy.
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 Slab lets you set on import versus which it computes — computed dates are a common surprise.
Schema Mapper Opens pre-loaded with the Confluence → Slab 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 Slab'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 — Slab, 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 Slab's importer expects -
Plan localisation and freeze the spec
Confirm how translated articles link to their source language in Slab, then version and sign off the mapping spec.
Confluence → Slab specifics
- Week 3–4: Bulk Extraction & Transformation
- Run the API pipeline to extract Confluence Storage Format, convert to Quill Delta/Markdown, and load into Slab.
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 Slab 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.
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 Slab 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 Slab, 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 Slab 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.
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 Equivalent
| Confluence field | Slab field | Notes |
|---|---|---|
| Space | Topic | 1:1 for simple structures. Complex spaces with deep page trees may need multiple nested topics. |
| Page | Post | Each page becomes a post. Slab posts can belong to multiple topics — Confluence pages live in exactly one space. |
| Page tree (parent-child) | Topic hierarchy + post ordering | Slab topics support nesting, but the depth is flatter than Confluence's arbitrary page trees. Deep hierarchies need flattening. |
| Blog Post | Post | No distinct blog type in Slab. Blog posts become regular posts, optionally grouped in a dedicated topic. |
| Labels | Topics (partial) | Slab has no label/tag system. If you use Confluence labels for categorization, map them to topic assignments. Watch for topic sprawl. |
| Comments | Comments (partial) | Slab supports post-level comments. Inline comments anchored to specific text lose their position. |
| Attachments | Inline in posts | Slab embeds images and files inline. Standalone attachments need re-uploading. |
| Macros | ❌ No equivalent | Jira macros, Table of Contents, status badges, panels, expand/collapse, and custom macros have no Slab equivalent. Content inside macros can sometimes be extracted as plain text; the macro behavior is lost. |
| Page restrictions | Topic permissions | Slab supports Open, Private, Secret, and Public topic permissions. Per-page restrictions don't exist — permissions are topic-level only. |
| Version history | ❌ Not migrated | Slab maintains its own version history from the import date forward. |
| Page templates | ❌ No equivalent | Slab has no template system. Recreate manually. |
| Databases, whiteboards | Separate conversion path | Confluence Cloud exports include database records but do not retain their content, data, or functionality. Convert to posts only when business value justifies it. (support.atlassian.com) |
Risk matrix
Per-object risk for this pair. Plan extra validation around anything marked high.
| Object | Risk | Notes |
|---|---|---|
| Confluence Macros (Jira, Status, Roadmap) | high | No Slab equivalent exists — content inside macros can sometimes be extracted as text but macro behavior is permanently lost |
| Page-Level Permissions | high | Slab only supports topic-level permissions — per-page restrictions cannot be replicated and require complete redesign |
| Internal Links | high | All Confluence URLs break unless a full page-ID-to-post-URL mapping and rewriting pass is performed |
| Version History | high | Not migrated — Slab maintains its own version history only from the import date forward |
| Page Templates | high | Slab has no template system — all Confluence templates must be recreated manually as reusable posts |
| Draw.io / Gliffy Diagrams | medium | Must be exported as PNG/SVG and embedded as images — the editable diagram capability is permanently lost |
| Expand / Collapse Sections | medium | No native equivalent in Slab — collapsed content is flattened inline |
| Blog Posts | medium | No distinct blog type in Slab — blog posts become regular posts optionally grouped in a dedicated topic |
| Attachments | medium | Size limits vary by plan (10 MB Free to 100 MB Business) — large PDFs or archives may exceed Slab's limits |
| Code Blocks | low | Maps cleanly to Slab's code blocks with language identifier normalization |
The hard parts
What makes this specific migration difficult, beyond the mechanics.
Macro Gap
Slab has no macro system. Jira macros, status badges, draw.io diagrams, expand/collapse, Page Include, and roadmap macros have no equivalent — each requires an explicit handling decision.
Internal Link Rewriting
All Confluence page-ID-based URLs break after migration. A two-pass approach is required — migrate all pages first, then rewrite every link using a confluence_page_id → slab_post_url mapping table.
1–3 Day Processing Blind Spot
The native importer provides no progress visibility during processing. Large XML exports can fail with OutOfMemory or timeout errors, and there is no incremental import — it's full space or nothing.
Permission Model Downgrade
Confluence has page-level restrictions. Slab has topic-level permissions only (Open, Private, Secret, Public). Per-post access control does not exist, requiring complete permission redesign.
Attachment Re-Hosting
Images referenced by URL in Confluence Storage Format point to the Confluence instance which will be decommissioned. Every attachment must be downloaded, re-uploaded to Slab, and relinked in the post content.
Tools used in this playbook
All free, all run entirely in your browser — nothing is uploaded.
FAQ
Does Slab have a native Confluence importer?
Yes. Slab admins can upload a Confluence XML space backup via Team Settings → Import & Export → Confluence. Processing takes 1–3 days depending on size and complexity. Macros, page-level permissions, unpublished drafts, and version history are not preserved.
Can I migrate Confluence to Slab with CSV?
Not through Slab's native path. Confluence can export CSV, but Slab's built-in importer specifically expects a Confluence backup or XML space export. CSV is intended for Confluence-to-Confluence imports.
What Confluence data is lost when migrating to Slab?
Confluence macros (Jira, status, draw.io, expand/collapse), page-level restrictions, version history, page templates, and unpublished drafts are all lost or unsupported in Slab. Internal links break unless rewritten. Attachments need re-hosting.
What are the API rate limits for Confluence and Slab?
Confluence Cloud enforces burst rate limits for API-token traffic and point-based quotas (65,000 points/hour) for Forge, Connect, and OAuth apps. Slab's GraphQL API enforces a complexity-based limit of 1,000 points per minute via a token bucket algorithm. Slab's API is only available on Business or Enterprise plans.
How do I preserve internal links when migrating from Confluence to Slab?
Use a two-pass approach: first migrate all pages and record a mapping of Confluence page IDs to new Slab post URLs, then walk every migrated post and replace Confluence URL patterns with Slab URLs using that mapping table. The native importer handles intra-space links partially but will break cross-space links.