This plugin allows Ikiwiki to display pages written with Mediawiki markup. It processes pages with the ".mediawiki" extension and is handy for converting from Mediawiki to Ikiwiki.



It works! The page you're reading now is written with Mediawiki markup, and so are most of the pages on this site. To see what features this plugin supports, see:

Test Pages

A few features, like tables and thumbnails, haven't been written yet. And there are still a few markup bugs (mostly involving <nowiki>). See the TODO list at the end of this page for more.



The only strange thing about installing this plugin is disabling the link plugin. This is a workaround for an Ikiwiki limitation and will hopefully go away in a future Ikiwiki release.

This plugin requries Ikiwiki 2.40 or higher.

Install Text::MediawikiFormat.

cpan Text::MediawikiFormat

Copy the plugin's code into your plugins directory.

cp lib/IkiWiki/Plugins

Add mediawiki to the list of enabled plugins in your setup file:

add_plugins => [qw{mediawiki}],


Turn on Prefix Directives

You also need to enable Prefix Directives. In your setup file:

prefix_directives => 1,

prefix_directives just says that all Ikiwiki directives will begin with '!'. Ikiwiki's old syntax used whitespace to tell the difference between a link and a preprocessor directive, causing ambiguities with Mediawiki links. Luckily, this has been fixed, complete with script that automatically converts pages to the new style.


Disable the Link Plugin

This is due to a limitation in the Ikiwiki render pipeline and hopefully will be fixed in a future Iki release. For now though (through 2.41+), you need to disable the Link plugin.

disable_plugins => [qw{link}],

This won't affect any of your other pages. The Mediawiki plugin will make sure that the link plugin gets called at the right times.

If you have any questions about configuration, you can look at the file used for this site here.



Now try creating a page that ends in .mediawiki and contains Mediawiki markup. Linking and redirects work, Mediawiki categories are translated seamlessly into Ikiwiki tags. Everything should just work as you expect. Definitely add a test to the test page if you see anything fail.

Now it's time to convert your old Mediawiki site.

If you want to attach a little icon to external links the way Mediawiki does, see External Links.


Development Thoughts

Converting Mediawiki markup to HTML is a nightmare. The only specification is the PHP spaghetti code and regular expressions scattered through Mediawiki's code base. The whole thing is basically one gigantic corner case. Tons of projects started have been started to render Mediawiki, very few actually do it well.

Here is a List of Renderers that were evaluated for this plugin. And some Category Notes.


Implementation Notes

  • The Mediawiki plugin supports Ikiwiki preprocessor directives. This means that you can take advantage of most (all?) Ikiwiki plugins in your Mediawiki pages.
  • Mediawiki's page names can include a trailing slash, Ikiwiki's can't.. [[Slash/]] will create a page named "Slash/" on Mediawiki and "Slash" on Ikiwiki.
  • Mediawiki's page names can include multiple intermediate slashes, Ikiwiki's can only have one. [[Apple//c]] creates a page named "Apple//c" on Mediawiki and "Apple/c" on Ikiwiki.
  • Mediawiki is case sensitive so "/subpage" and "/Subpage" are different pages. Ikiwiki generally isn't case sensitive. If both subpage and Subpage exist, Iki should load the page that's the closest match. The summary? Despite case-sensitivity differences, as long as you don't have broken links in your Mediawiki site, Mediawiki and Ikiwiki should always load the same page each link.



  • Handle categories / category links.
  • Inter-Wiki Links (this will handle languages too, i.e. [[fr:Main_Page]])
  • Make redirects support categories and trailing templates.
  • The plugin includes a partial workaround for this bug. Remove it when Ikiwiki includes a fix.
  • Automatically show a Table of Contents when an article has 4+ headings. Make sure it's inserted right before the first heading. We also should handle TOC/NOTOC.
  • Transclusion {{Another_Page}} and Thumbnailing (see below).
  • Bail if Text::MwF could not be found. It doesn't make any sense to interpret the links without also interpreting the markup. Better to have an error message than silent corruption.

Known formatting bugs (see Test/Markup Tests for discussion):

  • Tables. The formatter I'm using doesn't support them.
  • <br/> fails, <br> and <br /> work. It's a T:MwF bug. If you don't mind adding a single line to, a workaround is specified here.
  • <nowiki> sections cause a paragraph break to be inserted. A workaround is to ensure that the </nowiki> always appears at the end of a paragraph.
  • Spaces in header are turned into %20 in the anchors. They should be turned into underscores. Might be able to post-process this one with an HTML parser. Fix Shifty Shifts when this bug is fixed.


Ikiwiki Improvements

It would be nice to see these features added to Ikiwiki.

  • Signatures. Hitting ~~~~ would enter a link to the user's user page, ~~~~~ would enter a link and a date (it might be nice if ~~~ did that too). Here's the iki discussion.
  • Ikiwiki should allow plugins to submit their own scan/linkify routines for certain filetypes. That way, you would not have to turn off the Link plugin when installing the Mediawiki plugin; they could just coexist happily side-by-side.
  • Thumbnailing. Iki's img plugin seems to have a dubious future...? We'll wait for iki's image handling to stabilize before adding thumbnailing support to the Mediawiki plugin.
    • Example on M-10000
    • This is harder than it looks because Media offers a crazy combination of options: Mediawiki Docs. [[Image:{name}|{type}|{location}|{size}|{upright}|{border}|{caption}]]
  • Is it possible to edit a redirect page using the web interface? I don't think so... it redirects off before you can hit the edit button.