Migrating to DokuWiki from Other Wikis — MediaWiki, HTML Import, and Migration Tools

In this tutorial, you'll learn how to migrate content to DokuWiki from other wiki platforms, including importing from MediaWiki, converting HTML pages, using Migration tools, handling media files, and post-migration cleanup.

What You'll Learn

• Migration strategies and planning
• Importing from MediaWiki
• Converting HTML pages to DokuWiki syntax
• Handling media and file attachments
• Preserving page history during migration
• Post-migration cleanup and validation

Why It Matters

Migration is how you adopt DokuWiki when your content is locked in another platform. The flat-file architecture makes migration different from database-driven wikis. Without proper planning, you can lose formatting, links, and revision history. A structured migration Process preserves your content and saves hours of manual cleanup.

Real-World Use

A company decides to migrate from a MediaWiki installation to DokuWiki. They have 500 pages with complex formatting, categories, and media files. They export MediaWiki pages as XML, convert them to DokuWiki syntax using a migration tool, import the pages, manually fix formatting issues on 50 complex pages, and verify all internal links work. The migration takes 3 days instead of 3 weeks.

Learning Path

flowchart LR
  A[Upgrading] --> B[Migration]
  B --> C[Performance]
  C --> D[Security]
  D --> E[Production]
  E --> F[Conclusion]

Migration Planning

Step 1: Content Audit

Document what you are migrating:

• Number of pages
• Page formats and syntax used
• Media files (images, PDFs, etc.)
• User accounts (if migrating)
• Categories/tags structure
• Page history (if preserving)

Step 2: Map Namespace Structure

Map the old wiki's structure to DokuWiki namespaces:

Old MediaWiki Structure        New DokuWiki Structure
-------------------------      -------------------------
Main Page                      start
Category:Projects              projects:start
Projects:Alpha                 projects:alpha
Help:Installation              guides:installation
User:JohnDoe                   users:johndoe

Step 3: Choose Migration Method

MediaWiki to DokuWiki Migration

Step 1: Export from MediaWiki

# Export all pages from MediaWiki to XML
# Run from MediaWiki installation directory
php maintenance/dumpBackup.php --full > mediawiki-export.xml

Step 2: Use Conversion Tool

The mediawiki2dokuwiki tool converts MediaWiki syntax to DokuWiki syntax:

# Install the conversion tool
git clone https://github.com/username/mediawiki2dokuwiki.git
cd mediawiki2dokuwiki

# Convert the export file
python3 convert.py --input mediawiki-export.xml --output /tmp/dokuwiki-pages/

Step 3: Review Converted Files

Check the conversion output. MediaWiki and DokuWiki syntax have differences:

| MediaWiki | DokuWiki | |-----------|----------| | == Heading == | ===== Heading ===== | | '''bold''' | **bold** | | ''italic'' | //italic// | | <code>...</code> | <code>...</code> (same) | | [[Page]] | [[page]] | | [[Page|text]] | [[page|text]] (same) |

Step 4: Import to DokuWiki

# Copy converted files to DokuWiki
cp -r /tmp/dokuwiki-pages/* /var/www/html/wiki/data/pages/

Step 5: Run Indexer

php bin/indexer.php -f

HTML to DokuWiki Conversion

For HTML pages (from Confluence, WordPress, or static HTML), use pandoc or a custom script.

Using Pandoc

# Convert HTML to DokuWiki format
pandoc input.html -f html -t dokuwiki -o output.txt

Limitations of Automated Conversion

Automated conversion is not perfect. Common issues:

• Tables may not convert correctly
• Custom templates/widgets are lost
• Embedded media may need manual relinking
• Advanced formatting (colors, spans) is lost

Plan for manual cleanup of 10-20% of pages.

Preserving Page History

DokuWiki stores revision history in data/attic/ and data/meta/. To preserve history during migration:

Option 1: Keep Both Wikis

Keep the old wiki accessible as read-only for historical reference. Users can access old revisions on the old wiki.

Option 2: Import Revisions

Write a script that creates fake revisions with timestamps:

<?php
// import-revisions.php

$pageId = 'projects:roadmap';
$revisions = array(
    array('time' => '2026-01-15 10:00:00', 'content' => '...', 'editor' => 'admin'),
    array('time' => '2026-02-20 14:30:00', 'content' => '...', 'editor' => 'jdoe'),
    array('time' => '2026-03-10 09:00:00', 'content' => '...', 'editor' => 'admin'),
);

$atticDir = DOKU_INC . 'data/attic/' . dirname(str_replace(':', '/', $pageId));
if (!is_dir($atticDir)) {
    mkdir($atticDir, 0777, true);
}

foreach ($revisions as $rev) {
    $timestamp = strtotime($rev['time']);
    $filename = basename(str_replace(':', '/', $pageId));
    $atticFile = $atticDir . '/' . $filename . '.' . $timestamp . '.txt.gz';
    
    // Compress and save revision
    file_put_contents('compress.zlib://' . $atticFile, $rev['content']);
}

Media File Migration

Step 1: Export Media Files

# Copy all media files from source
cp -r /old-wiki/images/* /var/www/html/wiki/data/media/

Step 2: Organize by Namespace

Preserve the namespace structure in data/media/:

data/media/
├── projects/
│   ├── alpha-diagram.png
│   └── beta-screenshot.png
├── guides/
│   └── installation-step1.png
└── team/
    └── photo.jpg

Step 3: Update Internal Links

Media file references in pages may need updating. Search for old media paths:

# Find pages referencing old media paths
grep -r "old-media-path" data/pages/

Post-Migration Tasks

1. Verify All Pages Exist

# Count imported pages
find data/pages/ -name "*.txt" | wc -l

2. Check Internal Links

DokuWiki shows broken links with a different style. Browse through major sections and click links.

3. Test Search

php bin/indexer.php -f
# Then search for several terms that should return results

4. Check Media Files

# Count imported media files
find data/media/ -type f | wc -l

5. Verify Key Pages

Check these critical pages:

• Start page
• Navigation/sidebar
• Most-linked pages (check the wiki for link statistics)
• Recently modified pages from the old wiki

6. Update Redirects

Create redirects for old page URLs that external sites may link to:

~~REDIRECT>new-page-id~~

Migration Script Example

#!/bin/bash
# full-migration.sh

OLD_WIKI_DIR="/var/www/old-wiki"
NEW_WIKI_DIR="/var/www/html/wiki"

echo "Step 1: Export pages from old wiki..."
# (platform-specific export command)

echo "Step 2: Convert syntax..."
# Run conversion tool

echo "Step 3: Import pages..."
cp -r /tmp/converted-pages/* "$NEW_WIKI_DIR/data/pages/"

echo "Step 4: Import media..."
cp -r "$OLD_WIKI_DIR/images/"* "$NEW_WIKI_DIR/data/media/"

echo "Step 5: Set permissions..."
chown -R www-data:www-data "$NEW_WIKI_DIR/data/"
chmod -R 777 "$NEW_WIKI_DIR/data/"

echo "Step 6: Rebuild index..."
php "$NEW_WIKI_DIR/bin/indexer.php" -f

echo "Step 7: Clear cache..."
php "$NEW_WIKI_DIR/bin/cleanup.php" --cache

echo "Migration complete. Please verify manually."

Common Mistakes

1. Not planning namespace mapping: Randomly placing imported pages without a namespace plan creates a chaotic wiki. Map old categories to namespaces first.
2. Trusting automated conversion completely: Automated tools miss context-dependent formatting. Budget time for manual review of 10-20% of pages.
3. Forgetting to update internal links: Old wiki's internal links may have different formats. Search for and fix broken links.
4. Not preserving old wiki URLs: External sites linking to your old wiki will have broken links. Create redirects for important pages.
5. Skipping user notification: If you are migrating a team wiki, tell users about the migration, what changes to expect, and how to find migrated content.

Practice Questions

1. What are the main steps in planning a migration from MediaWiki to DokuWiki?
2. What syntax differences between MediaWiki and DokuWiki require attention during migration?
3. How would you preserve page revision history during a migration?
4. Challenge: Perform a complete migration from a test MediaWiki installation to DokuWiki. Create 10 pages in MediaWiki with various formatting (headings, tables, links, images, categories). Export them, convert the syntax, import to DokuWiki, and verify: all content is preserved, links work correctly, images display, categories are mapped to namespaces, and search finds all content. Document any conversion issues you encountered and how you resolved them.

FAQ

Mini Project

Goal: Plan and execute a test migration.

1. Set up a test wiki (any platform or a set of HTML files) with at least 10 pages
2. Export the content in a portable format (XML, HTML, or text)
3. Convert the content to DokuWiki syntax using available tools
4. Import the converted files into a test DokuWiki installation
5. Verify all 10 pages display correctly
6. Fix any formatting issues
7. Test internal links between pages
8. Verify media files are accessible
9. Create redirects for any changed page names
10. Document the migration process with timings and issues encountered

What's Next

Migration brings content from other platforms. Now learn about performance optimization to keep your DokuWiki fast as it grows.