How To Transition from GitHub Wiki to MediaWiki

Any growing company should value preserving institutional knowledge and best practices by writing them down and making them widely available to all.

Since the source code for this site is stored on GitHub, we originally packaged the documents and knowledge we wanted to share in the GitHub wiki that came with our repo. This was a good solution at first, but was not scalable to our needs. GitHub wikis are minimalist and its lack of a search functionality made it useless when working with our large collection of documents.

You, too, can convert from a GitHub Wiki to a MediaWiki

It took us only 10 not-so-easy steps!

After experimenting with different wiki packages, we decided to switch to MediaWiki. It had the features we wanted (i.e. search and automatic categorization), and was available through a one-click install through Digital Ocean.

Here’s what we did to move all 51 pages from GitHub to MediaWiki:

  • After MediaWiki was installed on our droplet, we made a backup of our GitHub wiki by cloning the wiki repo locally. As of this post writing, the MediaWiki version included on the droplet is 1.25, which is not the most current version of MediaWiki. I note this because I downloaded the wrong version of an extension a few times.
  • We then added a markdown parser to handle the difference between the default input syntax for MediaWiki, Wiki Markup, and the default for the cloned pages, Markdown. This is one of many MediaWiki extensions available. Adding this parser is a multi-step process, since the PHP Markdown Extra library is not packaged with it.
  • Once the parser was installed, it was time to lock down the wiki and keep our pages private. These settings had to be modified slightly when the GoogleLogin extension was installed.
  • We made our sidebar blocked to anonymous users and added a robots.txt file.
  • We didn’t want users to have to remember another password for the wiki, so we decided to add the GoogleLogin extension. The first step was to set up a Google Developers account and add the Google+ API to our wiki application. For the API to work correctly, we needed to set up a domain for our wiki – Google doesn’t like raw IPs. We also used the allowed domains setting on the GoogleLogin extension to lock down logins to only allow e-mail addresses.
  • We added content. It was a manual process, done by copying and pasting from a local copy of the GitHub wiki to the new MediaWiki. Using the categorization syntax, we preserved the old hand-built categories from the GitHub wiki.
  • We increased the upload limit for our file uploads.
  • Once the pages were imported and categorized, work was done to customize the sidebar and main page. MediaWiki comes with Special Pages, and the Special:UncategorizedPages page was very helpful in catching uncategorized articles, including this un-linked one.
  • I’d also like to note that during this process, there was a lot of editing of LocalSettings.php. Be prepared to get your hands dirty. Syntax highlighting also continues to be a tricky problem. The MarkdownExtraParser extension doesn’t seem to handle blocks of code very well, and the GeSHi syntax higlighting wants to escape > and < characters. We’re working on it.

While this process was time consuming, it’s nice to have the most powerful and extendable wiki platform backing our internal knowledge store.

More Posts by Lee Gillentine: