How to Migrate from Confluence to X402

By X402 Team | Last Updated: February 2026

Goal

What You'll Achieve

• Complete export of Confluence content
• Organized X402 repository structure
• Content converted to markdown format
• Links and images preserved
• Team transitioned to new workflow

Prerequisites

• Confluence Space Admin access
• Git installed locally
• GitHub/GitLab account
• pandoc installed (for conversion)
• 2-4 hours for small space (<50 pages)
• 1-2 days for large space (>200 pages)

Time Required

Migration Overview

Phase 1: Pre-Migration Planning

1. Audit current Confluence content
2. Decide what to migrate
3. Plan X402 batch structure
4. Set migration timeline

Phase 2: Export and Convert

1. Export from Confluence
2. Convert HTML to markdown
3. Clean up conversion artifacts

Phase 3: Organize in X402

1. Create batch structure
2. Organize content logically
3. Fix links and images

Phase 4: Verify and Launch

1. Validate all content
2. Train team on X402
3. Deprecate old Confluence

Step-by-Step Instructions

Phase 1: Pre-Migration Planning (30 minutes)

Step 1: Audit Your Confluence Space

Create content inventory:

# Log into Confluence and list all pages
Or use this quick inventory template


cat > confluence-inventory.md <<'EOF'
Confluence Content Inventory


Space: [Space Name]
Total Pages: [Count]
Last Updated: [Date]

Content by Type

User Guides: [count]
API Documentation: [count]
How-To Articles: [count]
Meeting Notes: [count]
Other: [count]


Priority Assessment
Must Migrate (Critical)

[Page 1]
[Page 2]


Should Migrate (Important)

[Page 3]
[Page 4]


Consider Migrating (Nice to have)

[Page 5]


Don't Migrate (Outdated/Irrelevant)

[Old page 1]
[Old page 2]

EOF

Step 2: Plan X402 Structure

Map Confluence structure to X402 batches:

# Migration Plan

Confluence Space → X402 Batches

Confluence: "Getting Started" section (10 pages)
→ X402: batch-001-getting-started/

Confluence: "API Reference" section (25 pages)
→ X402: batch-002-api-reference/
→ X402: batch-003-api-examples/

Confluence: "Guides and Tutorials" (15 pages)
→ X402: batch-004-user-guides/
→ X402: batch-005-tutorials/

Confluence: "Internal Processes" (8 pages)
→ X402: batch-006-internal/ (private repo)

Step 3: Set Timeline

## Migration Timeline

Week 1: Preparation and Export

Mon: Audit content, plan structure
Tue-Wed: Export and convert
Thu-Fri: Organize into batches


Week 2: Cleanup and Verification

Mon-Tue: Fix links, clean markdown
Wed: Team training session
Thu-Fri: Parallel running (both systems)


Week 3: Transition

Mon: Official switch to X402
Tue-Thu: Support team with questions
Fri: Archive Confluence, celebrate!

Phase 2: Export and Convert (1-3 hours)

Step 4: Export from Confluence

Method 1: Space Export (Recommended)

1. Go to Confluence Space Settings
2. Click "Content Tools" → "Export"
3. Choose "HTML" export format
4. Select "Custom Export"
5. Uncheck "Comments" (unless needed)
6. Click "Export"
7. Download ZIP file

Save to organized location:

mkdir confluence-export
cd confluence-export
unzip ~/Downloads/space-export.zip

Method 2: API Export (For Large Spaces)

#!/bin/bash
export-confluence.sh

CONFLUENCE_URL="https://your-company.atlassian.net"
SPACE_KEY="DOCS"
USERNAME="your-email@company.com"
API_TOKEN="your-api-token"

Get all pages in space
curl -u "$USERNAME:$API_TOKEN" \
  "$CONFLUENCE_URL/wiki/rest/api/content?spaceKey=$SPACE_KEY&limit=1000" \
  > pages.json

Extract page IDs and export each
jq -r '.results[].id' pages.json | while read page_id; do
  curl -u "$USERNAME:$API_TOKEN" \
    "$CONFLUENCE_URL/wiki/rest/api/content/$page_id?expand=body.storage" \
    > "page-$page_id.json"

echo "Exported page: $page_id"
done

Step 5: Install Conversion Tools

# Install pandoc (HTML to Markdown converter)
macOS
brew install pandoc

Ubuntu/Debian
sudo apt-get install pandoc

Windows (use Chocolatey)
choco install pandoc

Verify installation
pandoc --version

Step 6: Convert HTML to Markdown

Convert all HTML files:

#!/bin/bash
convert-confluence.sh


Create output directory
mkdir markdown-output

Convert all HTML files to markdown
for html_file in confluence-export/.html; do
  filename=$(basename "$html_file" .html)

# Convert using pandoc
  pandoc -f html -t markdown \
    "$html_file" \
    -o "markdown-output/${filename}.md"

echo "Converted: $filename"
done

echo "Conversion complete!"

#!/bin/bash
clean-markdown.sh

for file in markdown-output/.md; do
  # Remove Confluence macro artifacts
  sed -i 's/<ac:structured-macro[^>]>//g' "$file"
  sed -i 's/<\/ac:structured-macro>//g' "$file"


# Remove empty HTML tags
  sed -i 's/<span[^>]>//g' "$file"
  sed -i 's/<\/span>//g' "$file"

# Fix excessive newlines
  sed -i '/^$/N;/^\n$/D' "$file"

# Convert info panels
  sed -i 's/{info}/> ℹ️ Note:/g' "$file"
  sed -i 's/{tip}/> 💡 Tip:/g' "$file"
  sed -i 's/{warning}/> ⚠️ Warning:/g' "$file"

echo "Cleaned: $file"
done

Phase 3: Organize in X402 (1-2 hours)

Step 8: Create X402 Repository

# Create and initialize repository
mkdir x402-docs
cd x402-docs
git init

Create main INDEX
cat > INDEX.md <<'EOF'
Documentation (Migrated from Confluence)

Batches


[ ] batch-001-getting-started — In Progress (0/10 titles)
[ ] batch-002-api-reference — Not Started (0/25 titles)
[ ] batch-003-user-guides — Not Started (0/15 titles)


Instructions


Each batch is a separate folder
Add titles to batch INDEX.md as unchecked items
Complete work files in batch folder
Check off items as completed
Update batch status line above when done


Migration Notes
Migrated from Confluence on: 2024-11-23
Original space: DOCS
Total pages migrated: 50
EOF

Step 9: Organize into Batches

Create batches and move files:

# Create batch directories
mkdir -p batch-001-getting-started
mkdir -p batch-002-api-reference
mkdir -p batch-003-user-guides


Move files to appropriate batches
mv markdown-output/installation-guide.md batch-001-getting-started/
mv markdown-output/quick-start.md batch-001-getting-started/
mv markdown-output/authentication-api.md batch-002-api-reference/
mv markdown-output/users-api.md batch-002-api-reference/

Create batch INDEX files
cat > batch-001-getting-started/INDEX.md <<'EOF'
Batch 001 — Getting Started (Migrated)

Status: Complete

Content Items


[x] Installation Guide
[x] Quick Start Tutorial
[x] Configuration Basics


Notes
Migrated from Confluence "Getting Started" section
Original pages reviewed and updated during migration
All links verified
EOF

Step 10: Handle Images and Attachments

Organize media files:

# Create images directory in each batch
mkdir -p batch-001-getting-started/images
mkdir -p batch-002-api-reference/images


Copy images from Confluence export
cp confluence-export/attachments/.png batch-001-getting-started/images/
cp confluence-export/attachments/.jpg batch-002-api-reference/images/

Update image paths in markdown
for file in batch-/\.md; do
  # Update image references
  sed -i 's|/download/attachments/|images/|g' "$file"
  sed -i 's|confluence-export/attachments/|images/|g' "$file"
done

Phase 4: Verify and Launch (1-2 hours)

Step 11: Fix Internal Links

Update Confluence links to markdown links:

#!/bin/bash
fix-links.sh

Create link mapping file
cat > link-mapping.txt <<'EOF'
Old Confluence URL → New markdown file
https://company.atlassian.net/wiki/spaces/DOCS/pages/123/Installation → batch-001-getting-started/installation-guide.md
https://company.atlassian.net/wiki/spaces/DOCS/pages/124/API → batch-002-api-reference/authentication-api.md
EOF

Replace links in all markdown files
while IFS='→' read old_url new_path; do
  old_url=$(echo "$old_url" | xargs)  # trim whitespace
  new_path=$(echo "$new_path" | xargs)

for file in batch-/\.md; do
    sed -i "s|$old_url|$new_path|g" "$file"
  done
done < link-mapping.txt

Step 12: Validate Migration

Run validation checks:

#!/bin/bash
validate-migration.sh


echo "Migration Validation Report"
echo "==========================="

Count migrated pages
total_pages=$(find batch- -name ".md" -not -name "INDEX.md" | wc -l)
echo "Total pages migrated: $total_pages"

Check for broken links
echo
echo "Checking for broken internal links..."
broken_links=0
for file in batch-/\.md; do
  links=$(grep -o '\.\' "$file" | sed 's/.](\(.\))/\1/')

for link in $links; do
    dir=$(dirname "$file")
    target="$dir/$link"

if [ ! -f "$target" ]; then
      echo "Broken link in $file: $link"
      broken_links=$((broken_links + 1))
    fi
  done
done

if [ $broken_links -eq 0 ]; then
  echo "✓ All internal links valid"
else
  echo "✗ Found $broken_links broken links"
fi

Check for unconverted Confluence macros
echo
echo "Checking for unconverted macros..."
unconverted=$(grep -r "{" batch-/\.md | grep -v "

Check for missing images

for img in $images; do if [[ ! "$img" =~ ^http ]]; then # Skip external images dir=$(dirname "$file") img_path="$dir/$img"

if [ ! -f "$img_path" ]; then echo "Missing image in $file: $img" missing_images=$((missing_images + 1)) fi fi done done

if [ $missing_images -eq 0 ]; then echo "✓ All local images present" else echo "✗ Found $missing_images missing images" fi

echo echo "===========================" echo "Validation complete!"

Step 13: Create Templates


Confluence export won't include templates - create now:

cat > templates/guide-template.md <<'EOF'

[Title] — Guide

Overview

Prerequisites

Steps

Step 1: [First Step]

Step 2: [Second Step]

Troubleshooting

Next Steps

Quality Standards

• [ ] All steps tested
• [ ] Screenshots current
• [ ] Links verified
• [ ] Ready for production

Step 14: Commit Initial Migration

Add all files

Create comprehensive commit

Migrated content:

• 50 pages from DOCS space
• Converted HTML to markdown
• Organized into 6 batches
• Fixed internal links
• Preserved images and attachments

Batches created:

• batch-001: Getting Started (10 pages)
• batch-002: API Reference (25 pages)
• batch-003: User Guides (15 pages)

Post-migration tasks:

• Team training scheduled
• Confluence space marked read-only
• Migration validation complete

Push to remote

Team Transition

Step 15: Train Your Team

Training session agenda (60 minutes):

X402 Training for Team

Session 1: Overview (15 min)

• Why we migrated from Confluence
• Benefits of X402
• Tour of new repository

Session 2: Basic Workflow (20 min)

• How to find documentation
• How to create new content
• How to edit existing content
• How to submit changes (pull requests)

Session 3: Hands-On Practice (20 min)

• Everyone makes a small edit
• Submit a pull request
• Review process demonstration

Session 4: Q&A (5 min)

• Answer questions
• Distribute cheat sheet

Create quick reference guide:

X402 Quick Reference

Find Documentation

# Clone repository
git clone https://github.com/company/docs.git
cd docs

Search for content
grep -r "keyword" batch-/

Step 16: Parallel Running

Run both systems temporarily:

Troubleshooting

Issue: Conversion produces garbled text

Cause: Confluence macros not handled by pandoc

Solution: Manual cleanup required:

Issue: Images not displaying

Cause: Image paths incorrect after migration

Solution:

Issue: Tables poorly formatted

Cause: Confluence table HTML doesn't convert cleanly

Solution: Use table formatter:

Or manually recreate tables:

Issue: Links broken after migration

Cause: Confluence uses page IDs, X402 uses file paths

Solution: Create redirect mapping:

Post-Migration Checklist


Immediate (Week 1)

[ ] All content migrated
[ ] Links validated and fixed
[ ] Images present and displaying
[ ] Team trained on X402
[ ] Confluence marked read-only


Short-term (Month 1)

[ ] Update external links pointing to Confluence
[ ] Search engine redirects configured
[ ] Team comfortable with X402 workflow
[ ] First new content created in X402


Long-term (Month 3)

[ ] Confluence space archived
[ ] All bookmarks updated
[ ] Documentation improved with X402 features
[ ] Team productivity increased


Benefits Realized Post-Migration

Cost Savings