MediaWiki Migration Tools - Developer Guide

🚀 MediaWiki Migration Tools

Open-source toolkit for migrating Azure DevOps Wiki content to MediaWiki

Complete Guide

🛠️ Migration Tools

🔍

Migration Planner

✅ Ready

Analyse your Azure DevOps Wiki structure and estimate migration complexity

• Content analysis • Time estimation • Risk assessment

👀

Content Previewer

✅ Ready

Preview how your content will convert before running the migration

• Side-by-side comparison • Interactive preview • Export to HTML

🚀

Azure DevOps Migrator

✅ Ready

Main migration tool for Azure DevOps Wiki to MediaWiki content transfer

• Batch processing • Error recovery • Progress tracking

🔧

Validation Tool

🚧 In Progress

Validate migrated content for accuracy and completeness

• Content verification • Link validation • Quality reports

📊 Current Status

✅ Available Tools

Core migration tools are ready: migration_planner.py, content_previewer.py, azure_devops_migrator.py, and validation_tool.py. These provide the essential functionality for Azure DevOps Wiki to MediaWiki migration.

🚧 In Development

Enhanced template management, automated backup systems, and advanced analytics are currently being developed. Check our roadmap for planned features.

⚠️ Beta Status

This toolkit is in active development. While core functionality is stable, always test with non-production data first and maintain backups.

🚀 Quick Start Guide

Get up and running with MediaWiki Migration Tools in 5 simple steps

📋 Prerequisites

Python 3.8 or higher
Azure DevOps access token
MediaWiki admin credentials
Git (for cloning the repository)

1

Install Dependencies

Set up Python environment and required packages

                                        pip install -r requirements.txt
                                    

2

Configure Connection

Set up Azure DevOps and MediaWiki credentials

                                        python setup_config.py --azure-token YOUR_TOKEN --mediawiki-url YOUR_URL
                                    

3

Analyze Content

Run migration analysis to understand your content

                                        python migration_planner.py --wiki "YourWikiName"
                                    

4

Preview Migration

Preview how your content will convert

                                        python content_previewer.py --page "YourPageName"
                                    

5

Execute Migration

Run the full migration process

                                        python azure_devops_migrator.py --wiki "YourWikiName"
                                    

🎯 Next Steps

⚠️ Important Notes

Always backup your data before migration
Test with a small wiki first
Review converted content manually
Images require manual upload process

🛠️ Available Tools

Comprehensive toolkit for Azure DevOps to MediaWiki migration

🔍 Migration Planner Ready

Analyze your Azure DevOps Wiki structure and plan migration strategy

                                            migration_planner.py
                                        

Features:

Content complexity analysis
Migration time estimation
Risk assessment report
Dependency mapping

📖 Documentation

👀 Content Previewer Ready

Preview content conversion before migration

                                            content_previewer.py
                                        

Features:

Side-by-side comparison
Syntax highlighting
Interactive preview
Export to HTML

📖 Documentation

🚀 Azure DevOps Migrator Ready

Main migration tool for Azure DevOps Wiki to MediaWiki

                                            azure_devops_migrator.py
                                        

Features:

Batch processing
Error recovery
Progress tracking
Rollback support

📖 Documentation

🎨 Template Manager Planned

Import and manage MediaWiki templates

                                            mediawiki_import.py
                                        

Planned Features:

Template detection
Infobox conversion
Custom template mapping
Batch import support

📖 Documentation

🔧 Available Utility Tools

✅ Ready to Use

getting_started.py - Interactive setup and environment configuration
validation_tool.py - Validate migrated content accuracy
mediawiki_import.py - Basic MediaWiki template import

🚧 Planned Features

backup_manager.py - Automated backup management
link_validator.py - Comprehensive link validation
migration_analytics.py - Advanced reporting dashboard
performance_monitor.py - Real-time migration monitoring

These tools are in development. Check our planned features section for progress updates.

💡 Getting Started with Tools

All tools include built-in help. Run any tool with --help to see available options and usage examples. View the complete tools reference for detailed documentation.

📚 Comprehensive Guides

Step-by-step guides for successful migration

🚀 Quick Start Guide

Get up and running in 15 minutes

What you'll learn:

Environment setup
Basic configuration
First migration test
Validation process

1

Install Dependencies

Python 3.8+, required packages

2

Configure Settings

Azure DevOps and MediaWiki credentials

3

Run Test Migration

Validate with sample content

📖 Complete Migration Guide

Comprehensive migration workflow

Complete process:

Pre-migration planning
Content analysis & mapping
Execution strategies
Post-migration validation

Phase 1: Assessment & Planning

Phase 2: Content Preparation

Phase 3: Migration Execution

Phase 4: Validation & Cleanup

View Guide

🛠️ How-To Guides

Task-specific instructions

Available guides:

🔄 Batch Processing

⚠️ Error Recovery

🎨 Custom Templates

🔗 Link Management

⚡ Performance Tuning

💾 Backup & Restore

All How-To's

📋 Specialised Documentation

🔧 Configuration

🎯 Best Practices

🚨 Troubleshooting

🔬 Advanced Topics

📚 Documentation Updates

Our documentation is continuously updated. Check the changelog for the latest updates and improvements.

💡 Examples & Use Cases

Real-world examples and success stories

🔧 Conversion Reference Guide

Before/after examples with manual fix guidance

Content types covered:

Basic markdown conversion
Complex tables and lists
Code blocks and syntax highlighting
Images and media handling
Links and cross-references
Templates and macros

Manual fix patterns:

Common formatting issues
Table alignment problems
Link reference updates
Template parameter mapping

15+

Fix Examples

View Reference

📊 Content Analysis Examples

See how the tools analyse different content types

Simple Text Pages

Complexity: Low

✅ 99%+ conversion accuracy

Tables & Lists

Complexity: Medium

✅ 95% conversion accuracy

Complex Formatting

Complexity: High

⚠️ May require manual review

View Analysis Examples

⚡ Quick Start Templates

Ready-to-use configuration templates

Available templates:

📄 Basic Setup

Simple wiki migration template

🎨 Advanced Features

Templates, macros, custom styling

🏢 Enterprise

Large-scale migration setup

Browse Templates

🛠️ Getting Started Examples

📝 Command Line Usage

Real command examples you can copy and use

$ python migration_planner.py --wiki "MyWiki"
✅ Analysing wiki structure...
📋 Found 150 pages, estimated 2 hours

Plan your migration strategy
Preview content conversion
Run dry-run tests first
Validate results afterwards

View Full Guide

🔧 Common Migration Patterns

Typical workflows and best practices

1. Plan & Analyse
Run migration_planner.py to understand your content

2. Preview & Test
Use content_previewer.py for sample pages

3. Migrate & Validate
Execute migration with validation checks

🔗 Code Samples

Basic Usage

Advanced Configuration

Custom Scripts

# Basic usage example - Command line tools

# 1. Analyse your Azure DevOps Wiki
python migration/migration_planner.py --wiki "YourWikiName"

# 2. Preview content conversion
python migration/content_previewer.py --page "YourPageName"

# 3. Run migration with dry-run first
python migration/azure_devops_migrator.py --wiki "YourWikiName" --dry-run

# 4. Execute actual migration
python migration/azure_devops_migrator.py --wiki "YourWikiName"

🚀 Getting Started

This toolkit provides the essential tools for Azure DevOps Wiki to MediaWiki migration. Start with the migration planner to analyse your content, then use the content previewer before running your migration. Follow the quick start guide for step-by-step instructions.

🚀 Getting Started Script

The interactive setup script that guides you through environment configuration and tool selection

📋 What It Does

Environment Detection: Automatically detects your OS, Python version, and shell
Setup Configuration: Creates .toolkit_env file with optimised settings
Interactive Menu: Provides guided access to all migration tools
Dependency Checks: Verifies required packages and provides installation guidance
Platform Optimisation: Adapts to Git Bash, PowerShell, macOS, and Linux environments

🎯 Available Options

1. Azure DevOps Wiki Migration
Complete migration workflow setup

2. Content Analysis & Planning
Run migration_planner.py with guidance

3. Content Preview & Validation
Preview content conversion before migration

4. Local MediaWiki Environment
Start Docker-based development environment

5. View Documentation
Access toolkit documentation

6. Help & Support
Troubleshooting and support information

💻 Usage Examples

# Basic usage
python getting_started.py

# Test mode (safe to experiment)
python getting_started.py --test-mode

💡 Recommendation

Start here if you're new to the toolkit. The script will guide you through the entire setup process and help you choose the right tools for your migration needs.

🔧 Technical Details

🏗️ Environment Configuration

Creates a .toolkit_env file with:

Python executable path
Shell and OS detection
Docker Compose command preference
Git Bash compatibility settings
Toolkit directory paths

🎛️ Platform Support

Optimised for:

Windows: Git Bash, PowerShell, Command Prompt
macOS: Terminal, iTerm2, Zsh, Bash
Linux: All major distributions and shells
Docker: Both Compose v1 and v2

🚀 Best Practice

Always run python getting_started.py first when setting up the toolkit in a new environment. It will detect your system configuration and set up optimal defaults for your platform.

🎯 Planned Features

Future enhancements and tools currently in development

📋 Development Status

This toolkit is actively developed. While core migration functionality is stable and tested, additional features are being added based on user feedback and common use cases. Check back regularly for updates.

🛠️ Utility Tools In Development

backup_manager.py
Automated backup and restore functionality for MediaWiki instances

link_validator.py
Comprehensive link validation and automatic fixing

cleanup_tool.py
Clean up temporary files, logs, and migration artifacts

health_checker.py
System health monitoring and performance checks

30%

📊 Analytics & Reporting Planned

migration_analytics.py
Detailed migration reports and success metrics

content_analyzer.py
Deep content analysis and pattern recognition

performance_monitor.py
Real-time migration performance monitoring

quality_checker.py
Automated content quality assessment

15%

🎨 Advanced Features Research

Template Engine v2
Advanced template conversion and management

Automated Testing Suite
Comprehensive migration validation tests

Web Dashboard
Browser-based migration management interface

Multi-source Support
Support for Confluence, Notion, and other wikis

5%

📅 Development Roadmap

Phase 1 - Core Stability

✅ Complete validation_tool.py improvements
✅ Enhanced error handling and logging
✅ Documentation improvements

Next Phase - Utility Tools

🚧 backup_manager.py development
🚧 link_validator.py implementation
🚧 Enhanced template management

Future Enhancement - Analytics & Reporting

📋 migration_analytics.py
📊 Performance monitoring tools
📈 Quality assessment framework

Under Consideration - Advanced Features

🌐 Web dashboard prototype
🔄 Multi-source support research
🧪 Automated testing framework

🤝 Community Input Welcome

Development priorities are influenced by community feedback. If you have specific needs or feature requests, please create an issue on GitHub or start a discussion.

🤝 Get Support

We're here to help you with your migration

❓ Frequently Asked Questions

Q: How long does a typical migration take?

A: Migration time depends on the size and complexity of your wiki. Small wikis (10-50 pages) typically take 15-30 minutes, whilst larger wikis (500+ pages) may require several hours.

Q: What if my content doesn't convert correctly?

A: Our tools achieve 95%+ accuracy for standard content. Use the content previewer to identify issues before migration. Complex tables or custom formatting may require manual adjustment.

Q: Can I customise the migration process?

A: Yes, all tools support configuration files, command-line parameters, and can be integrated into custom scripts for advanced workflows.

Q: Do I need to migrate all content at once?

A: No, you can migrate in batches. Use the --page or --folder options to migrate specific content subsets.

Q: What about images and attachments?

A: Images and attachments require manual upload to MediaWiki. The migrator identifies all media files and provides instructions for bulk upload.

🚨 Common Issues & Solutions

Authentication Failed

Check your Azure DevOps PAT has Wiki read permissions. Verify MediaWiki bot credentials are correct.

Content Formatting Issues

Use content_previewer.py to preview conversions. Complex tables may need manual adjustment.

Migration Timeout

For large wikis, use --batch-size 10 to process in smaller chunks. Consider running overnight.

Missing Dependencies

Run pip install -r requirements.txt in the migration folder to install all dependencies.

📞 Contact & Community

🐛 GitHub Issues

Report bugs and request features on our GitHub repository.

💬 Discussions

Join the conversation in GitHub Discussions.

📖 Documentation

Contribute to docs via pull requests.