X402 Content Migration

By X402 Team | Last Updated: February 2026

Direct Answer

Migrating content to X402 involves exporting source content to markdown, organizing into batch folders, applying X402 templates, updating links and images, verifying quality standards, and committing to Git—with strategies varying based on source system (CMS, Wiki, Google Docs, or legacy documentation).

Detailed Explanation

Migration Overview

Planning Phase

Before migrating content:

Audit existing content - Catalog what you have
Prioritize migration - What to migrate first
Define batches - How to group content
Choose tools - Export and conversion utilities
Set timeline - Realistic migration schedule

Migration Principles

Migrate in batches - Don't try to move everything at once
Improve during migration - Fix issues as you convert
Verify quality - Check each piece meets standards
Maintain accessibility - Old content stays available during migration
Test thoroughly - Verify links, formatting, accuracy

Source System Strategies

From WordPress

Export Process:

# 1. Export from WordPress Tools: WordPress export feature or wp-cli wp export --dir=./wp-export 2. Convert to markdown Tool: wordpress-to-markdown npm install -g wordpress-export-to-markdown

wordpress-export-to-markdown --wizard

Conversion workflow:

# Directory structure after export:
/wp-export/
  post-1/
    index.md
    images/
  post-2/
    index.md
    images/

Organize into X402 batches:
batch-001/
  post-1.md
  post-2.md
  images/
    post-1-image.jpg
    post-2-image.png

Template mapping:

# WordPress post metadata

title: Original Post Title
date: 2024-01-15
categories: [Tech, Tutorial]


Becomes X402 format
Original Post Title — Tutorial

Overview
[Content from WordPress post...]

Cleanup checklist:

[ ] Remove WordPress shortcodes
[ ] Convert HTML to markdown
[ ] Update image paths
[ ] Fix internal links
[ ] Apply X402 template structure
[ ] Add quality standards section

From Confluence

Export Process:

# 1. Export space from Confluence Settings → Space Tools → Export Choose HTML export 2. Convert HTML to markdown Tool: pandoc

for file in export/.html; do pandoc -f html -t markdown "$file" -o "${file%.html}.md" done

Handling Confluence specifics:
# Confluence macros need manual conversion: Code block macro {code:java} public class Example {} {code}
Becomes markdown:
java public class Example {}
Info panel macro {info} Important note here {info} Becomes: > Note: Important note here

Batch organization:
Confluence Space: "Product Documentation" → batch-001-overview/ → batch-002-installation/ → batch-003-configuration/ → batch-004-troubleshooting/

From Google Docs

Export Process:
# 1. Use Google Docs → Download → Markdown Or use Google Drive API 2. Clean up exported markdown
Google Docs markdown export is decent but needs cleanup

Script: scripts/clean-gdocs-export.sh

#!/bin/bash

for file in .md; do
  # Remove Google Docs artifacts
  sed -i 's/<span[^>]>//g' "$file"
  sed -i 's/<\/span>//g' "$file"


# Fix heading levels (Google uses wrong levels)
  sed -i 's/^##### /### /' "$file"
  sed -i 's/^#### /## /' "$file"

# Clean up extra newlines
  sed -i '/^$/N;/^\n$/D' "$file"

echo "Cleaned $file"
done

Migration workflow:

Export batch of Google Docs

Run cleanup script

Organize into batch folder

Apply X402 template structure

Add quality standards

Review and commit

From GitHub Wiki

Export Process:
# Clone wiki repository git clone https://github.com/user/repo.wiki.git Wiki files are already markdown!
Just need to reorganize into X402 structure

Migration script:

#!/bin/bash

wiki_dir="repo.wiki"
batch_num=1

Group wiki pages into batches by topic
for topic in "Getting-Started" "API" "Guides"; do
  batch_name=$(printf "batch-%03d-%s" $batch_num "$topic")
  mkdir -p "$batch_name"

# Move relevant pages
  for page in "$wiki_dir"/$topic.md; do
    cp "$page" "$batch_name/"
  done


# Create INDEX.md
  echo "# Batch $(printf "%03d" $batch_num) — $topic" > "$batch_name/INDEX.md"
  echo "## Status: In Progress" >> "$batch_name/INDEX.md"
  echo "## Content Items" >> "$batch_name/INDEX.md"

# Add items
  for file in "$batch_name"/.md; do
    [ "$file" = "$batch_name/INDEX.md" ] && continue
    echo "- [ ] $(basename "$file" .md)" >> "$batch_name/INDEX.md"
  done

batch_num=$((batch_num + 1))
done

From Legacy Documentation

Common formats:

Plain text files (.txt)
Old HTML documentation
PDF documents
Word documents (.doc, .docx)

Conversion tools:

# PDF to markdown
pdftotext document.pdf - | pandoc -f plain -t markdown -o document.md

Word to markdown
pandoc -f docx -t markdown input.docx -o output.md

HTML to markdown
pandoc -f html -t markdown input.html -o output.md

Plain text (add structure manually)
Create template and paste content into sections

Migration Workflow

Step 1: Content Audit

Create inventory of existing content:

# content-audit.md

High Priority (Migrate First)

User guides (50 pages)
API documentation (30 endpoints)
Getting started tutorials (10 docs)


Medium Priority

Internal processes (25 docs)
Troubleshooting guides (15 docs)


Low Priority (Archive)

Outdated blog posts (100+)
Old release notes (50+)


Don't Migrate

Duplicate content
Severely outdated material
Content marked for deletion

Step 2: Batch Planning

Organize migration into logical batches:

# migration-plan.md

Phase 1: Core Documentation (Weeks 1-2)

batch-001: Product overview and introduction
batch-002: Installation and setup guides
batch-003: Basic configuration


Phase 2: User Guides (Weeks 3-4)

batch-004: User interface guides
batch-005: Common workflows
batch-006: Advanced features


Phase 3: Technical Content (Weeks 5-6)

batch-007: API documentation
batch-008: Integration guides
batch-009: Developer resources


Phase 4: Support Content (Week 7)

batch-010: Troubleshooting guides
batch-011: FAQ compilation
batch-012: Best practices

Step 3: Export and Convert

For each batch:

# 1. Export from source system
./scripts/export-source.sh batch-001

2. Convert to markdown
./scripts/convert-to-markdown.sh batch-001

3. Review converted files
ls batch-001/

4. Clean up conversion artifacts
./scripts/clean-converted-files.sh batch-001

Step 4: Apply X402 Structure

Transform converted content to X402 format:

Before (raw export):

# User Authentication

This document explains authentication.

Login Process
Users can log in with username and password.

Password Reset
Click forgot password link.

After (X402 template applied):

# User Authentication — Guide

Overview
This guide explains how user authentication works in the system,
including login processes, password management, and security best practices.

Login Process
Standard Login
Users can authenticate using:

Username and password
Email and password
Social login providers


Steps

Navigate to login page
Enter credentials
Click "Sign In"
Access granted upon success


Password Management
Password Reset
If users forget their password:

Click "Forgot Password" link
Enter email address
Check email for reset link
Create new password
Log in with new credentials


Password Requirements

Minimum 8 characters
At least one uppercase letter
At least one number
At least one special character


Quality Standards

[x] All sections complete
[x] Steps tested and verified
[x] Screenshots added
[x] Links verified
[x] Ready for production

Step 5: Update Links and References

Fix broken links from migration:

Script: scripts/fix-migrated-links.sh

#!/bin/bash

batch=$1

Old wiki links: [[Page Name]]
New markdown links: Page Name

for file in "$batch"/.md; do
  # Convert wiki-style links
  sed -i 's/\[\[\([^]]\)\]\]/\1/g' "$file"

# Fix spaces in filenames
  sed -i 's/ /-/g' "$file"

# Update image paths
  sed -i 's/!\[\([^]]\)\](\([^)]\))//g' "$file"
done

Step 6: Quality Verification

Check each migrated piece:

## Migration Quality Checklist

[ ] Content converted accurately
[ ] Formatting correct (headings, lists, code blocks)
[ ] Images copied and paths updated
[ ] Links work correctly
[ ] Code examples tested
[ ] X402 template applied
[ ] Quality standards section added
[ ] No conversion artifacts remain
[ ] Spelling and grammar checked
[ ] Technical accuracy verified

Step 7: Commit and Track

Commit migrated batches:

git add batch-001/ git commit -m "$(cat <<'EOF' Migrate batch-001: Product overview documentation Migrated from Confluence space "Product Docs" 8 documents converted to markdown Applied X402 template structure Updated all links and images Verified technical accuracy

All items in batch complete and reviewed. EOF )"

Handling Special Content Types

Code Examples

Ensure code blocks have correct language tags:

# Before (no language)

function example() { return true; }


After (language specified)

javascript function example() { return true; }

Tables

Convert HTML tables to markdown:

# Before (HTML)
<table>
  <tr><th>Feature</th><th>Status</th></tr>
  <tr><td>Login</td><td>Complete</td></tr>
</table>

After (Markdown)
Feature Status
Login Complete

Feature	Status
Login	Complete

Images and Media

Organize media files:

batch-001/
  content-file.md
  images/
    diagram-1.png
    screenshot-2.png
  videos/
    demo.mp4 (or link to external hosting)

Update image references:

# Old (absolute URL)


New (relative path)

Dealing with Migration Challenges

Large Content Volume

Problem: Hundreds or thousands of documents

Solution:

Automate as much as possible
Migrate in phases over weeks/months
Prioritize high-value content
Archive or delete obsolete content
Consider parallel migration teams

Poor Quality Source Content

Problem: Original content is incomplete or incorrect

Solution:

Use migration as opportunity to improve
Mark items needing SME review
Create issues for content gaps
Don't migrate known-bad content
Update as you migrate

Complex Formatting

Problem: Tables, diagrams, interactive elements

Solution:

Simplify complex tables
Convert diagrams to images
Replace interactive elements with static alternatives
Link to external tools where needed
Document limitations

Broken or Missing Links

Problem: Internal links don't work after migration

Solution:

Create link mapping file
Update all references
Use search and replace
Validate with link checker
Add redirects if needed

Post-Migration Tasks

Validation

Run comprehensive checks:

# Check all migrated content
./scripts/batch-report.sh

Verify links
./scripts/check-links.sh

Run quality checks
markdownlint batch-/
cspell "batch-/.md"

Generate migration report
echo "Migration Complete: $(date)" > migration-report.md
echo "Batches migrated: $(ls -d batch- | wc -l)" >> migration-report.md
echo "Total items: $(grep -r "^- \[x\]" batch-*/INDEX.md | wc -l)" >> migration-report.md

Old Content Handling

Decide what to do with original content:

Options:

Keep available during transition period
Set up redirects from old URLs
Add sunset notice to old system
Archive completely once migration verified
Delete after archival backup

Timeline example:

Week 1-4: Migration in progress, both systems active
Week 5-8: New X402 system primary, old system read-only
Week 9+: Old system archived, X402 only

Team Training

Ensure team can work with X402:

Training session on X402 workflow
Documentation of processes
Office hours for questions
Pairing on first few items
Feedback gathering to improve processes

Quality Standards

[x] Meets brand voice requirements
[x] Follows formatting standards
[x] Includes all required elements
[x] Ready for production

Start Building with X402

Get our free X402 Implementation Starter Kit with ready-to-use templates, code examples, and best practices.

What is included:

Quick-start implementation templates
API integration examples
Configuration best practices guide

Get the Free Starter Kit