Migrate from Confluence

Migrate from Confluence

Folio imports a Confluence page or a whole page tree as Markdown. It works with Confluence Cloud and with on-premises (Server or Data Center) installations. Run a test import first: not every macro has an equivalent, and some things do not come over at all.

What is imported

• Pages as Markdown, with the page tree kept as folders (a page with imported children becomes a folder with its own page; sibling order is kept).
• Attachments and images: downloaded and stored with the space. Images show in the page; other files (PDF, video and so on) become links. A file over 64 MB or one that fails to download is skipped, and the page still imports.
• Panels become callouts; code blocks, checklists, tables (with nested lists), expand sections (collapsible blocks) and status lozenges (as Folio status tags) are converted. A pagetree macro becomes Folio's page-tree block; Jira issue macros become links to the issue key when a Jira address can be resolved.
• Links between imported pages are rewritten as relative links. Links to Confluence content you did not import point at the original Confluence address.
• Whiteboards from Confluence Cloud become Excalidraw boards.
• The imported root never replaces the space's home page.

What is not imported

Page restrictions and space permissions, comments (inline comment markers are dropped, the text stays), labels, page history and authorship, and macros without an equivalent (they may be simplified or lost). You rebuild access in Folio (Sharing and Permissions).

Step by step

1. Get a token. Cloud: an Atlassian API token plus your account email. On-prem: a Personal Access Token.
2. Open the importer. User menu, Import from Confluence. (Not available on the public demo.)
3. Paste the page URL of the root page you want. A tree import starts from this page.
4. Choose the authorization type: Cloud (email + token) or On-prem (PAT). Tick "Save for future imports" to keep the token, stored encrypted; saved tokens are filled in when the host matches.
5. Choose the target: a new space, or an existing space plus a path inside it.
6. Include child pages (on by default) and start. Progress shows pages imported out of the total, and the import keeps running in the background if you close the dialog.
7. Open the space and check it: headings, tables, callouts, images, links, attachments.
8. Rebuild access: map Confluence space permissions to Folio roles (admin, editor, viewer) and Confluence page restrictions to Folio page access. A restriction on a parent does not protect its children in Folio, so lock each page that must stay closed.

If the token is rejected the dialog says so (invalid, no access, page not found, rate limited, Confluence unavailable). Confluence reports a missing page and missing access the same way, so check the link and the token's rights.

Tips

• Import one small section first and compare it with the original.
• Import big spaces tree by tree rather than in one go.
• For a single page, the free Confluence to Markdown converter runs in your browser and uploads nothing.
• After the import, use the graph's Unresolved links switch to find links that point nowhere (Graph).

Limits

Not every macro converts. The importer reads pages through the Confluence REST API, so it needs a token that can read them. Confluence whiteboards come only from Cloud.

See also

Folio vs. Confluence · Confluence alternatives · Confluence to Markdown tool · LIMITATIONS.md