How to Migrate from Confluence to BookStack

Confluence pricing ($6.05-11.55/user/month) and Atlassian's push toward cloud mean many teams are looking for self-hosted alternatives. BookStack is the most Confluence-like open source option — organized by shelves, books, chapters, and pages. Here's how to migrate.

Why BookStack?

BookStack's hierarchy mirrors Confluence naturally:

Confluence	BookStack
Space	Shelf or Book
Page tree	Chapters
Pages	Pages
Labels	Tags
Comments	Comments
Attachments	Attachments

What Transfers

Content	Status
✅ Pages and content	HTML export → import
✅ Page hierarchy	Recreate as chapters/pages
✅ Text formatting	Well preserved via HTML
✅ Images	Embedded in export
✅ Tables	Supported
✅ Code blocks	Supported
⚠️ Macros	Some need manual conversion
⚠️ Attachments	Export separately, re-upload
❌ Page comments	Not preserved in export
❌ Page history	Not preserved
❌ Confluence macros	Replace with BookStack equivalents

Step 1: Deploy BookStack

# Docker Compose
docker run -d \
  --name bookstack-db \
  -e MYSQL_ROOT_PASSWORD=secret \
  -e MYSQL_DATABASE=bookstack \
  -e MYSQL_USER=bookstack \
  -e MYSQL_PASSWORD=secret \
  mysql:8.0

docker run -d \
  --name bookstack \
  --link bookstack-db:db \
  -e DB_HOST=db \
  -e DB_DATABASE=bookstack \
  -e DB_USERNAME=bookstack \
  -e DB_PASSWORD=secret \
  -e APP_URL=https://docs.yourdomain.com \
  -p 80:80 \
  solidnerd/bookstack

Default login: admin@admin.com / password — change immediately.

Step 2: Export from Confluence

Option A: Space export (recommended)

1. Go to the Confluence space → Space Settings → Content Tools
2. Click Export
3. Select HTML Export
4. Choose Full Export (all pages)
5. Download the ZIP

Option B: Individual pages

1. Open page → ⋯ → Export → Word or PDF
2. Repeat per page

Option C: API export (for large spaces)

# Export pages via Confluence REST API
curl -u email:api-token \
  "https://your-instance.atlassian.net/wiki/rest/api/content?spaceKey=MYSPACE&limit=100&expand=body.storage" \
  > confluence-export.json

Step 3: Import into BookStack

BookStack doesn't have a native Confluence importer, but several approaches work:

Approach 1: HTML import (best for most cases)

1. Extract the HTML export ZIP
2. Open BookStack → Create a Book for each Confluence space
3. Create Chapters for page tree sections
4. For each page: New Page → click the HTML editor → paste the HTML content
5. Clean up formatting as needed

Approach 2: Markdown conversion

# Convert HTML to Markdown using pandoc
for f in *.html; do
  pandoc "$f" -f html -t markdown -o "${f%.html}.md"
done

Then import Markdown files into BookStack pages.

Approach 3: API import (for automation)

# Create a book via API
curl -X POST https://docs.yourdomain.com/api/books \
  -H "Authorization: Token YOUR_TOKEN_ID:YOUR_TOKEN_SECRET" \
  -d '{"name": "Migrated Space", "description": "From Confluence"}'

# Create pages
curl -X POST https://docs.yourdomain.com/api/pages \
  -H "Authorization: Token YOUR_TOKEN_ID:YOUR_TOKEN_SECRET" \
  -d '{"book_id": 1, "name": "Page Title", "html": "<p>Content...</p>"}'

Step 4: Organize Structure

1. Create Shelves for top-level categories (Engineering, Product, HR, etc.)
2. Create Books within shelves (matching Confluence spaces)
3. Create Chapters for page groups
4. Move pages into appropriate chapters
5. Set permissions per shelf, book, or chapter

Step 5: Set Up Authentication

# LDAP (Active Directory)
AUTH_METHOD=ldap
LDAP_SERVER=ldap://your-ad-server:389
LDAP_BASE_DN=dc=yourdomain,dc=com
LDAP_DN=cn=admin,dc=yourdomain,dc=com

# SAML (Okta, Azure AD, etc.)
SAML2_ENABLED=true
SAML2_IDP_ENTITYID=https://your-idp.com
SAML2_AUTOLOAD_METADATA=true

BookStack supports LDAP, SAML, OIDC, and social login (Google, GitHub, etc.).

Step 6: Handle Confluence Macros

Confluence Macro	BookStack Equivalent
Code block	Code block (syntax highlighted)
Table of contents	Auto-generated sidebar
Info/Warning/Note panels	Callout blocks
Jira issue link	Manual link
Page include	Not available (link instead)
Expand/Collapse	Details block
Status label	Not available (use text)
Draw.io diagram	Embed as image

Cost Savings

Team Size	Confluence Standard	BookStack	Savings
10 users	$61/month	$10/month (VPS)	$612/year
25 users	$151/month	$15/month	$1,632/year
50 users	$303/month	$20/month	$3,396/year
100 users	$578/month	$40/month	$6,456/year

Migration Timeline

Week	Task
Week 1	Deploy BookStack, export Confluence, begin import
Week 2	Complete import, organize structure, set up auth
Week 3	Invite team, run both platforms
Week 4	Primary documentation moves to BookStack
Month 2	Sunset Confluence

---

Compare documentation platforms on OSSAlt — editing experience, organization, and self-hosting options side by side.