How to migrate from Confluence to BookStack

Move Confluence Cloud or Data Center to self-hosted BookStack: pick the export, fit page trees to four levels, import through the API, rebuild access, cut over.

Start with one workloadThe steps

Written for
The engineer who will do the work
Or run by Pilae
At a fixed price, then operated

In short

  • BookStack has no Confluence importer: each space leaves Confluence as an HTML or XML export, or through its REST API, and a script writes it into BookStack through the BookStack REST API.
  • BookStack has four fixed levels, shelf, book, chapter and page, so deeper Confluence page trees are folded into their parents or split into books before the import.
  • Page history starts again at the import and imported pages carry the importing account and date, so Confluence stays read-only, with its history, until it is closed.
  • Atlassian has announced that Confluence Data Center reaches end of life on 28 March 2029, when it becomes read-only and receives no further security fixes.
On this page (12)

Moving from Confluence to BookStack is an export and a rebuild through an API. BookStack has no Confluence importer, so every space leaves Confluence as an export, or through the Confluence REST API, and a script writes it into BookStack: books, chapters and pages first, then images, attachments and links. Copying the text is the easy part. The work is fitting page trees of any depth into BookStack’s four fixed levels, deciding what each macro becomes, and rebuilding access around your directory. This guide covers Confluence Cloud and Confluence Data Center, in the order we run the move.

Why teams move from Confluence to BookStack

Three reasons come up again and again.

  • A date for Data Center. Atlassian stopped selling Data Center subscriptions to new customers on 30 March 2026 and has announced end of life for its Data Center products on 28 March 2029. From that day Confluence Data Center is read-only and receives no security fixes. Atlassian’s own path is a move to Confluence Cloud; BookStack keeps the wiki on machines you control.
  • Where the documentation lives. A wiki of runbooks, policies and procedures is a map of how the organisation works. Self-hosted BookStack keeps it in a MariaDB database and a volume on your premises or in a region you choose, shown only to people who have signed in.
  • One edition, nothing held back. BookStack is MIT-licensed and has no paid tier. SAML2, OpenID Connect and LDAP sign-in, group sync, multi-factor authentication and the API are all in the one edition, and nothing is priced per user.

What you give up is real. Confluence has real-time co-editing; BookStack warns that someone else has started editing a page rather than merging their changes. BookStack’s structure stops at four levels where Confluence nests pages as deep as you like, and nothing in it replaces the Jira integration or the Marketplace apps a space may rely on. Where several people need to write the same page at the same moment, Outline is the other wiki Pilae runs for Confluence-style documentation. And someone has to run BookStack, which is the part Pilae takes on.

Step 1: inventory the spaces

List what is there before deciding anything.

  1. Every space, with its key, an owner, its number of pages and blog posts, and the date of its last edit. Spaces nobody has edited in a year are usually exported for the archive in step 2 and not migrated.
  2. The depth of each page tree. In BookStack a book holds chapters, a chapter holds pages, and nothing nests further: a top-level page can become a chapter and its children pages, and that is all. Note every top-level page whose branch has grandchildren. Those branches decide the map in step 3.
  3. The macros each space relies on. Confluence’s query language finds them. A CQL search such as macro = jira and space = OPS, run through the REST API, lists every page in the space that embeds Jira issues. Run it for each macro in the table in step 4 and for every Marketplace app installed.
  4. Page restrictions: pages that only some people or groups can view or edit. Step 5 rebuilds each one explicitly.
  5. Blog posts, comments and attachments worth keeping, and the size of the largest attachment, which sets BookStack’s upload limit.
  6. Links into Confluence from other tools: bookmarks, tickets, READMEs, chat channel topics. They all need a new target at cutover.

Step 2: choose the export for each deployment

What you can take out of Confluence depends on where it runs and on the format. On Cloud, a space admin opens Space settings, General, then Export space, and an organisation admin can block exports. On Data Center, someone with the Export Space permission opens Space tools, then Content Tools: the Export tab writes HTML or PDF, and Back up writes the XML.

Source Confluence Cloud Confluence Data Center
HTML export Pages the exporter can view, attachments in a folder per page. No blog posts, no page comments Pages the exporter can view, with attachments and, optionally, comments. No blog posts
XML export Meant for importing into Data Center; Atlassian does not list its contents. A site admin gets all Pages, comments and attachments, restricted pages included, and page history. Blog posts: see below
PDF export One document of pages. No blog posts, no comments One document of pages, with images only. No blog posts, no comments
REST API Pages in storage format, blog posts, comments, labels and attachments, item by item Pages in storage format, blog posts, comments, labels and attachments, through its own API

Both deployments document their exports in Export content to Word, PDF, HTML and XML, with a Data Center version of its own. Atlassian’s Data Center page is not consistent about blog posts in the XML backup: its table lists them, while its steps say the backup excludes them. Check one export before the script relies on them.

Then choose what the import reads:

  • On Data Center, the XML backup is the fullest record. It holds each page in Confluence’s storage format, an XHTML dialect in which macros, page links and images are elements of their own, along with comments, attachments and the historical versions of each page, and blog posts where that check finds them. It is also written in Confluence’s internal object model, with every page, version and body as a separate entry in entities.xml, so the script that reads it is the most work.
  • The HTML export is the simplest to read, and it is the format most community scripts expect. Macros arrive as whatever HTML Confluence rendered for them, or as nothing.
  • On Cloud, the HTML export holds neither blog posts nor page comments. When either matters, read the space through the Confluence REST API instead, which returns each page in storage format with its labels, comments and attachments.

Whatever the import reads, take an XML export and a PDF or HTML export of every space for the archive, including the spaces you retire, and keep them after Confluence closes.

Step 3: map each space onto four levels

BookStack has four levels: shelves hold books, books hold chapters and pages, and chapters hold pages. A chapter carries a short description but no page body of its own. Everything in a space has to land on one of those levels.

Confluence BookStack
A group of related spaces Shelf
Space Book, or a shelf of books for a large space
Space home page The book’s description, or its first page
Top-level page with children Chapter, with the page’s own text as its first page
Page Page
Page nested deeper than that Folded into its parent as a section, or its branch is a book
Blog post Page in a book of its own, with a chapter per year
Label Tag, found with a [label] search
Page properties Tags with a name and a value
Attachment Attachment on the same page
Embedded image Image in the page’s gallery
Page restriction Permissions on the chapter or the page
Comments Comments through the API, or kept in the archive
Page history Not imported: it stays in Confluence and in the XML export

Two rules settle most trees. A branch that is deep because it is large, such as a product’s whole documentation, becomes a book of its own, so the pages under its root become chapters. A branch that is deep because someone nested short pages, such as a page per meeting under a page per year, folds into fewer, longer pages. A book can sit on several shelves at once, so a space that served two departments needs no copy.

Write the map down as a file the import script reads: every Confluence page ID with its target book, chapter and page, or the parent it folds into. Owners sign off their section of the map before anything is imported.

Step 4: import into staging through the API

Build the staging instance as production will be: its own MariaDB, uploads in local_secure mode, and the sign-in from step 5. Then prepare it for the import.

  • An import account. Create a dedicated user whose role has the Access System API permission and rights to create content, and give it an API token. BookStack shows the token’s secret only once. Everything the script creates is created by this account.
  • The rate limit. The BookStack API limits how many requests each user can make per minute, through API_REQUESTS_PER_MIN. Raise it for the import window, and set it back afterwards.
  • Upload limits. Raise FILE_UPLOAD_SIZE_LIMIT, in megabytes, above the largest attachment from step 1, along with PHP’s post_max_size and upload_max_filesize and the web server’s own limit, such as NGINX’s client_max_body_size.

The order the script runs in

  1. Structure. Create shelves, books and chapters from the map, through /api/shelves, /api/books and /api/chapters.
  2. Pages. Create each page with POST /api/pages, as HTML so that it opens in the WYSIWYG editor, with its labels as tags and a changelog naming its Confluence page ID. BookStack asks for HTML kept to a single-block depth of plain elements, so Confluence’s layout sections and columns are flattened into a sequence of headings, paragraphs, lists, tables, code blocks and callouts.
  3. Images. Upload each image to the page’s gallery with POST /api/image-gallery (type gallery, uploaded_to the page ID) and replace its address in the HTML with the URL the call returns. Images sent inline as base64 data are extracted into the gallery automatically.
  4. Attachments. Upload files with POST /api/attachments, as a multipart request against the same page.
  5. Links. Once every page has a BookStack ID, rewrite internal links in a second pass. In the storage format, a link to another page names its title and, across spaces, its space key; links pasted as full addresses carry the page ID, or the space key and title. The map turns each one into BookStack’s permanent link form, /link/ followed by the page ID, which survives renames and moves.
  6. Comments and owners, if you keep them. POST /api/comments recreates a comment, posted by the import account on the day of the import, so the original author and date go into its first line. Each item’s owner can be set later through the content permissions endpoint, once the people have accounts.
# One page into a chapter, as HTML, with its Confluence labels as tags
curl -sS -X POST "https://wiki.acme.internal/api/pages" \
  -H "Authorization: Token ${BOOKSTACK_TOKEN_ID}:${BOOKSTACK_TOKEN_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "chapter_id": 42,
    "name": "Restore the billing database",
    "html": "<h2 id=\"bkmrk-before-you-start\">Before you start</h2><p>...</p>",
    "tags": [{ "name": "runbook" }, { "name": "owner", "value": "platform" }],
    "changelog": "Imported from Confluence page 2293771"
  }'

Imported pages show the import account as their creator and the import date as their last update. That is why Confluence stays readable, with its history and authors, until you close it.

What each macro becomes

Confluence macro In BookStack
Code block Code block, with its language
Info, note, tip and warning panels Callouts: info, success, warning and danger
Expand Collapsible block
Include page, excerpt include Include tag, {{@page_id}} or {{@page_id#bkmrk-section}}
Page properties Tags on the page
Page properties report A tag search such as [status=draft], linked from the page
Table of contents Nothing to convert: BookStack lists a page’s headings beside it
Children display and page tree Nothing to convert: the book’s sidebar shows its full hierarchy
Status Bold text, or a tag where people filter on it
Jira issues A link to the Jira filter, or a table of the issues at the import
Marketplace macros, diagrams, charts The rendered image, or plain content

An include tag pulls content in when the page is viewed, respects the reader’s permissions and works up to three levels of nesting. Included text is not indexed on the page that includes it, so a page built mostly of includes is found by its title.

Community tools, and how far they go

A few community projects do part of this. The BookStack HTML Importer, a small PHP project on GitLab put together to migrate Confluence to BookStack, creates one book from a space’s HTML export, with a page per HTML file named after the file, and its README says it does not handle attachments. A modified version published by another team formats page titles and places the books on a shelf. None of them is maintained by the BookStack project, and their READMEs do not mention macros, restrictions or comments. BookStack’s own collection of example API scripts carries a warning that the scripts may be outdated or buggy, and it has no Confluence script. Read and test any of them on a copy. The dependable route is a script of your own, kept in a repository next to the map.

A script can also write BookStack’s Portable ZIP format: one archive per book with its chapters, pages, tags, images and attachments, loaded through Import on the Books view or the /api/imports endpoint by a user with the Import content permission. It suits a book that is built offline and loaded in one go.

Run the whole import into staging, then ask owners to check their sections against Confluence: structure, images, attachments, includes and links. Nobody edits in staging. The final run in step 6 starts from a clean instance.

Step 5: connect sign-in and rebuild permissions

Connect sign-in before setting permissions, because permissions are granted to roles and the roles come from your directory.

  1. Sign-in. BookStack signs people in over OpenID Connect, SAML2 or LDAP, one method at a time, and the method replaces email-and-password login. For OpenID Connect through Keycloak or Entra ID, set AUTH_METHOD=oidc with your issuer, OIDC_USER_TO_GROUPS=true, the claim that carries groups in OIDC_GROUPS_CLAIM, and OIDC_REMOVE_FROM_GROUPS=true so that leaving a group removes the role at the next sign-in. Accounts are created at first sign-in and matched afterwards by their External Authentication ID, the sub claim by default. With Pilae, single sign-on comes from the Business plan, and our identity service sets up the connection.
  2. Roles. Create one role per directory group that needs access. A group matches a role by its display name, lowercased with spaces turned into hyphens, or by the values in the role’s External Authentication IDs field. Keep each role’s default content permissions narrow and grant access per book.
  3. Space permissions become book permissions. A group that could view or edit a space gets a role with view or edit on that book, and Everyone Else is set to no access where the space was closed. Permissions set on a book or chapter cascade to everything inside it unless an item has its own.
  4. Page restrictions become item permissions on the chapter or page that the restricted branch landed on, from the list in step 1.
  5. Shelf permissions do not cascade. A book can sit on several shelves, so BookStack never passes a shelf’s permissions down on its own. Copy them to the shelf’s books in one action from the shelf, or with php artisan bookstack:copy-shelf-permissions.

The default Admin role keeps every permission and cannot be restricted, so keep it to the people who run the wiki. The script can set all of this from the map through PUT /api/content-permissions/{type}/{id}, where an empty list of role permissions clears what an item had. Before the cutover, sign in as a member of each group and open a restricted page you should see and one you should not.

Step 6: freeze Confluence and cut over

Search is the last thing owners test. BookStack matches exact phrases in quotes, tags in square brackets such as [runbook] or [owner=platform], and filters in braces such as {type:page} or {in_name:restore}. Ask each owner to find five pages they know, and search for the Confluence hostname to catch links the rewrite missed. Date filters work from the import date, not the original edits.

Then freeze. On Data Center, a system administrator turns on read-only mode under General Configuration, Maintenance: people can view pages but not create or change them, a banner says so on every page, and system administrators can still export spaces. The feature needs a Data Center licence. On Cloud, give every group, user and user class in each migrated space the Viewer role, which views and comments on content but cannot edit it; on a site still moving to space roles, take every permission beyond viewing and commenting away from each of them. Permissions in Confluence Cloud add up, so a single remaining grant keeps editing open.

The cutover, in order

  1. Freeze: Confluence goes read-only, and a notice on every page names the date and the new address.
  2. Import: The final exports run, and the script imports them into a clean production BookStack.
  3. Check: Owners compare their sections, permissions are tested per group, and the link search runs.
  4. Repoint: Bookmarks, tickets, READMEs and chat topics move to BookStack addresses.
  5. Close: Confluence stays read-only for an agreed period, the final exports go to the archive, and the subscription ends.

Through that period both stay open: people write in BookStack, and look up history and original authors in the read-only Confluence. On Data Center, the old hostname can keep working after the server is switched off: a redirect built from the map sends each Confluence page address to its BookStack page. Keep the XML and PDF exports as the archive rather than a read-only Confluence server, because from 28 March 2029 that server receives no security fixes.

Running BookStack in production

A wiki the whole organisation reads needs a few things beyond the application.

  • MariaDB or MySQL, the only databases BookStack supports, one per instance.
  • Private uploads. With the default storage, images are served to anyone who has the link. STORAGE_TYPE=local_secure serves them only to people who have signed in.
  • Backups taken together. BookStack’s backup guide lists the database, the .env file, the image and attachment folders and any themes. A restore needs the original APP_KEY from .env, which encrypts multi-factor secrets.
  • Staying current. The project’s security policy supports only the latest release, so upgrades follow it closely rather than once a year.

Pilae operates BookStack this way, on its own MariaDB with uploads in local_secure mode, and with Gravatar and the public diagrams.net editor switched off or pointed inside your network. Backups of the database, the uploads and the .env file are taken at the same moment, daily, encrypted and stored offsite in the country your contract names, and on Enterprise a restore test runs every month and is recorded in the console. The Pilae Agent tests each upgrade on a copy, waits for your approval and applies it in your window. BookStack runs on your premises or on dedicated machines in Pilae Cloud, answering only on your private network.

Let Pilae run the move

Pilae runs Confluence to BookStack migrations at a fixed price: the space inventory, the exports, the map onto four levels with your owners, the import script and a staging import, sign-in and permissions, and the cutover. Then we operate BookStack for you under a contract that, from the Business plan, includes a monthly availability commitment with service credits. See migration services for what the fixed price covers, or tell us about your Confluence spaces and we will scope it.

Questions

Can BookStack import Confluence spaces directly?

No. BookStack has no Confluence importer, and its own site says there is no automated way to migrate from Confluence yet. Each space is exported from Confluence as HTML or XML, or read through the Confluence REST API, and written into BookStack through its REST API by a script. The script is where the four-level structure, the macros and the links are handled.

Do comments, blog posts and page history come across?

Page history does not: the BookStack API creates pages, not past revisions, so history starts again at the import and Confluence keeps its own until it closes. Blog posts are not in the HTML export. The REST API returns them, and the Data Center XML backup should too, though Atlassian's page contradicts itself on that, so check one export. They become pages in a book of their own. Comments can be recreated through the BookStack API, but each one is posted by the importing account on the day of the import, so the original author and date go into its text.

What happens to Confluence macros?

The import script converts each one. Code blocks, info panels and expand sections have direct BookStack equivalents. Include page becomes a BookStack include tag, and page properties become tags you can search. Jira issue lists, status lozenges and Marketplace macros have no equivalent and become links or plain text.

Is BookStack open source?

Yes. BookStack is MIT-licensed and comes in one edition. SAML2, OpenID Connect and LDAP sign-in, group sync, multi-factor authentication and the API are all in it. The project sells support plans, not features.

What has Atlassian announced for Confluence Data Center?

Atlassian stopped selling Data Center subscriptions to new customers on 30 March 2026, and existing customers can buy new subscriptions until 30 March 2028. On 28 March 2029, its Data Center products, Confluence included, reach end of life: they become read-only and receive no further security fixes, with extended maintenance offered to some customers by exception.

How long does a Confluence to BookStack migration take?

It depends on the shape of the content more than its size: how deep the page trees go, which macros the spaces rely on, and how many page restrictions have to be rebuilt. The inventory in step 1 settles all three. Pilae quotes the move at a fixed price once it is done.

Let us run the move for you

An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.

Start with one workload

  • Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
  • CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.