Migrating from MediaWiki to Confluence

Surely there’s a tool for this?

By far the most common question at this point will be whether a tool exists for performing such a migration, and the answer is of course yes. There are a variety of options that will convert your Wikitext formatted MediaWiki content into a Confluence style, and then port it over.

Sometimes there’s no replacement for manual (digital) labour

Manually migrating an entire documentation system? Really!?

I can definitely understand if this seems unpalatable, especially if you’re staring at a MediaWiki instance with articles numbering in the thousands (or maybe more!). Luckily for us we were only looking at just over a hundred, and the exercise actually proved to be a useful activity for refining, culling and just generally updating our documentation. In fact, it represented the single biggest refinement of our documentation in its history, which can only be a good thing, especially during the acquisition and integration phase.

Lessons learned from manually migrating 100+ articles from MediaWiki to Confluence

Lesson #1: Using categories (and a lack thereof) to track our migration

Luckily for us, our MediaWiki did not make use of categories. This meant I was able to create 3 categories to track how our migration was progressing:

  • Migrated to Confluence space 1
  • Migrated to Confluence space 2
  • Not being migrated to Confluence
The moment this message finally appeared was a truly wonderful one
How the top of each migrated page looks

Lesson #2: Copy-pasting is incredibly effective (thanks Confluence!)

It may sound a little cliché to suggest that the best way of moving content from one system to another is to copy-paste it, but surprisingly, it really is.

Lesson #3: Image quality is massively reduced

If you do use the above method of copy-pasting content, bear in mind that the image quality sent over will be the one currently on display on the Wiki, not the original, which may or may not be completely different resolutions.

See the “Original file” link at the bottom-left

Lesson #4: Articles in Confluence will be owned by whoever transfers them

One thing I only discovered after migrating 100+ articles, is that the person who migrates them then owns them in the eyes of Confluence, and is therefore subscribed to email alerts every time someone makes a change.

Lesson #5: URLs may need to be updated (but are relatively easy to find)

Given that MediaWiki is a system of interconnected documents, it’s a fair bet that your articles feature many internal links. This of course is a problem when you move to Confluence, as you don’t want users being sent back to the legacy MediaWiki instance when they click a link (especially after that system is decommissioned).

In closing

All in all, the migration took around 5–15 minutes per article. That’s a small price to pay for ensuring your content is up to date, but I could see why the prospect may be a little more daunting if your articles number in the thousands.



Full-stack software developer from the UK, author of the Aftermath book series, full time tech-nerd.

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Duncan McArdle

Duncan McArdle


Full-stack software developer from the UK, author of the Aftermath book series, full time tech-nerd.