Migration Guides for Documentation Tools

Migrating between documentation tools requires planning, content conversion, and validation. Learn how to plan migrations from Confluence to Markdown, WordPress to Hugo, and between static site generators.

What You'll Learn

You will learn how to plan and execute documentation migrations, what tools to use for content conversion, and how to validate the Migration results.

Why It Matters

Migration is inevitable. Teams outgrow tools, costs increase, or requirements change. A well-planned migration preserves content quality. A poorly planned migration loses formatting, breaks links, and frustrates users.

Real-World Use

DodaTech migrated from a WordPress-based documentation site to Hugo. The migration involved exporting 500+ pages, converting HTML to Markdown, restructuring the content hierarchy, and setting up a new build pipeline.

flowchart LR
  A[Audit Source Content] --> B[Choose Target Platform]
  B --> C[Export and Convert]
  C --> D[Validate Conversion]
  D --> E[Set Up Pipeline]
  E --> F[Redirect Old URLs]
  F --> G[Launch and Monitor]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Migration Planning Checklist

- [ ] Inventory all existing documentation pages
- [ ] Identify content that should not be migrated (outdated, duplicated)
- [ ] Choose target SSG or platform
- [ ] Plan URL structure for the new site
- [ ] Test conversion with a sample of pages
- [ ] Set up redirects from old URLs to new URLs
- [ ] Plan migration in phases (not all at once)
- [ ] Communicate the migration timeline to users
- [ ] Test the new site before launch
- [ ] Monitor for issues after launch

Confluence to Markdown Migration

# Export Confluence pages as HTML
# Convert HTML to Markdown using pandoc
pandoc confluence-export.html -f html -t markdown -o output.md

# Or use a specialized tool
pip install confluence-to-markdown
confluence-to-markdown --space DOCS --output content/

For Confluence-specific elements:

# Handle Confluence macros and attachments
# Macros may need manual conversion
# Attachments download to an assets folder
confluence-to-markdown --space DOCS --output content/ --download-attachments

WordPress to Hugo Migration

# Export WordPress content using the built-in exporter
# WordPress Admin > Tools > Export > All content

# Install wordpress-export-to-markdown
npm install -g wordpress-export-to-markdown

# Convert WordPress XML to Markdown
wordpress-export-to-markdown \
  --input wordpress-export.xml \
  --output content/ \
  --post-type post,page

SSG-to-SSG Migration

MkDocs to Hugo

# MkDocs content is already in Markdown
# The main migration tasks are:
# 1. Move files from docs/ to content/
# 2. Convert mkdocs.yml to hugo.yaml
# 3. Update internal links
# 4. Recreate navigation structure

# Move content
mkdir -p content/docs
cp -r docs/* content/docs/

# Convert mkdocs.yml navigation to Hugo
python3 convert-mkdocs-nav.py mkdocs.yml > hugo.yaml

WordPress to Markdown Conversion Script

import html2text
import os

def convert_wp_html_to_markdown(html_content, output_path):
    """Convert WordPress HTML content to Markdown."""
    converter = html2text.HTML2Text()
    converter.body_width = 0
    converter.protect_links = True
    converter.ignore_images = False

    markdown = converter.handle(html_content)

    with open(output_path, 'w') as f:
        f.write(markdown)

URL Redirect Strategy

# Netlify _redirects file
# Old URL -> New URL
/docs/old-page/ /docs/new-page/ 301!
/tutorials/old-tutorial/ /guides/new-tutorial/ 301!

# Wildcard redirects for structural changes
/wordpress-docs/* /docs/:splat 301!

Common Mistakes

1. Migrating Everything Without Review

Migration is an opportunity to remove outdated content. Do not migrate pages that are no longer relevant.

2. Not Testing the Conversion

Always test the conversion with a representative sample. Batch conversion may produce unexpected formatting issues.

3. Ignoring Redirects

Old URLs will be indexed by search engines and bookmarked by users. Without redirects, users encounter 404 errors.

4. Migrating in One Big Bang

Large migrations should happen in phases. Migrate one section at a time and validate before proceeding.

5. Not Preserving Metadata

Page metadata (author, date, tags) is often lost during conversion. Map metadata fields between source and target.

Practice Questions

1. What is the first step in any documentation migration?

Audit the existing content to understand what exists, what is outdated, and what should be preserved.

2. Why should you use redirects during a migration?

Redirects ensure that existing bookmarks and search engine indexes point to the correct new URLs.

3. What tool converts HTML documentation to Markdown?

Pandoc is the most versatile tool. html2text is another option for simpler conversions.

4. Why should migration happen in phases?

Phased migration allows validation at each step and reduces the risk of a failed launch.

5. Challenge: Export a sample of 5 pages from Confluence or WordPress. Convert them to Markdown using pandoc or a specialized converter. Validate the output and fix any formatting issues. Plan a URL redirect strategy.

FAQ

Mini Project

Create a migration plan from a hypothetical Confluence documentation space to Hugo. Inventory 10 pages, export them as HTML, convert to Markdown with pandoc, validate the output, create a redirect map, and write a migration timeline with phases.

What's Next

The Documentation Tools module provides a broader view of the documentation tool landscape. Continue to Documentation Tools for a deep dive into each tool category.