Adopt MediaWiki as Our Internal Knowledge Management System | Initium Lab | Exploratory Arm of Initium Media

Adopt MediaWiki as Our Internal Knowledge Management System

In the search of internal knowledge system, we have considered multiple options, such as Confluence, MediaWiki, Gollem etc. After some exploration, we settled with MediaWiki and started our journey since March. In this post, we would like to share our experience with MediaWiki at Initium Lab. While there are extensive documentation for MediaWiki, we will mainly focus on using MediaWiki from the view of internal knowledge system, e.g., private installation and multi-user collaboration.

For those who haven’t heard about MediaWiki, it was developed to serve the needs of the Wikipedia encyclopedia project back in 2002. It is licensed under the GNU General Public License (GPL). MediaWiki is written in PHP programming language, and stores data in database such as MySQL. It still powers various Wikipedia projects, which serves 15 billion page views per month 1.

From technical point of view, MediaWiki projects can be roughly divided into two parts, core and extensions. MediaWiki core project maintain the essential features, and provides rich “hooks” allowing additional PHP code to extend functionality with extensions. Currently there are more than 2,000 extensions available. Wikimedia also uses extensions to develop new features. Take a look at the extensions installed on English Wikipedia.

Before we start, it should be noted that everything we mentioned in this post, e.g. the installation of MediaWiki and various extensions, are open sourced on Github. We use Docker and Docker Compose to manage MediaWiki and dependent services like database, which allows one to set up a new internal wiki website within ten minutes.

Screenshot of Initium Lab wiki

User System

MediaWiki has a fine-grained user system, allowing to define groups and group-based permissions. For a private MediaWiki installation, the following settings are active:

  • Only users in the sysop group can create new account
  • Anonymous users cannot view or edit any page (with exceptions such as the user login page)

You can also integrate with existing user system in your enterprise, such as using LDAP or Google Login.

MediaWiki has many built-in permission settings, for example, only users with administrator group can edit MediaWiki namespace. Defining new permission is straightforward. For example, if we would like to allow anonymous read/write requests from the parsoid and ocg services (defined in docker-compose.yml ), we just need the following line added to the settings file.

1
2
3
4
5
6
7
// Allow anonymous requests from parsoid and ocg
if ($_SERVER['REMOTE_ADDR'] === "172.27.1.3" ||
$_SERVER['REMOTE_ADDR'] === "172.27.1.4"
) {
$wgGroupPermissions['*']['read'] = true;
$wgGroupPermissions['*']['edit'] = true;
}

For the details of user rights management, please check the MediaWiki documentation.

Content Management

MediaWiki organizes content in Pages. Each page has a title and text, where the title is used to construct the page url such as https://wiki.initiumlab.com/Page_Title. Page texts are usually written in Wikitext format. While it is not as popular as Markdown, wikitext provides more rich and flexible formatting. For example, tables have a much better support in wikitext compared to Markdown. Check out wiki markup for available markups.

Every edit to a page is saved permanently as a Revision, and you can easily compare difference between revisions, rollback to a certain revision in history etc. Renaming the page leaves a redirection for the original page by default, so you can be assured that users will not reach a 404 page later.

Being a wiki system, MediaWiki has first-class support for internal link (wikilink). You can easily link to another wiki page using the [[Page Title]] syntax. In addition, the Interwiki extension allows linking to other wikis with the same syntax prefixed with the wiki name. For example, [[mw:Extension:Interwiki]] links to the MediaWiki page: https://www.mediawiki.org/wiki/Extension:Interwiki. You can also define your own interwiki prefixes.

Organization

To organize multiple pages, MediaWiki uses a Category system. Each page can be associated with one or more categories. Each category gets its own page to list all pages belonging to the category. Check category documentation for more details.

In addition, MediaWiki use Namespace to distinguish content types. By default, all main contents are in the main namespace. Other namespaces includes Category namespace, Talk namespace, MediaWiki namespace etc. You can create additional namespaces to organize your content. Check namespace help for details.

Another feature we used a lot at Initium Lab is Subpage. Pages can be organized in a hierarchical structure by using subpages. For example (screenshot shown below), our style guide page Initium Coding Convention has multiple subpages to describe individual programming language conventions, such as Python and Javascript. Subpage provides really nice and convenient features. For example, breadcrumbs linking to parent pages are automatically generate, and concise wikilinks such as using [[/Python/]] to link to the Python subpage. Check subpage help for details.

Files and media

In MediaWiki, Files lives in the File: namespace, and each file gets its own page, which can be used to describe the file and manage versions. All the file revisions are preserved on the server. Linking to a file is the same with linking to another page. MediaWiki provides extensive support for media files, such as images. You can specify size, alignment and border when you are embedding an image, and you can embed multiple images at once in a grid gallery. For PDF files, the system can generate thumbnails for each page and embed like images. Check out the documentation for details.

External Content

While we would like to keep everything in one place, some content are better off on living on other platforms. For example, our event videos are hosted at YouTube for public viewing. In this case, we still want to embed the video in our event wiki page, and play the video without leaving our wiki page. By default, MediaWiki does not allow iframe tag for security reason and thus you cannot embed a YouTube video. With the help of the Widgets extension, we can define iframes templates in Widget namespace, and then we can embed third-party content by including widget templates. Internally, we have support the following external content:

  • Widget:YouTube, to embed event video recordings to the corresponding wiki page
  • Widget:Google Presentation, for embedding Google Slides, such as slides for internal workshops
  • Widget:Google Calendar, for embedding our internal Google Calendar

A sample code of Youtube widget is followed. The code segment included in <includeonly> block is a displayed on the compiled production page.

<noinclude>
This widget allows you to add a [https://developers.google.com/youtube/player_parameters YouTube video player] to your wiki page.

== Using this widget ==
For information on how to use this widget, see the [http://www.mediawikiwidgets.org/YouTube widget description page on MediaWikiWidgets.org].

== Copy to your site ==
To use this widget on your site, just install the [https://www.mediawiki.org/wiki/Extension:Widgets MediaWiki Widgets extension] and the copy [{{fullurl:{{FULLPAGENAME}}|action=edit}} full source code] of this page to your wiki, as an article called '''{{FULLPAGENAME}}'''.
</noinclude><includeonly><iframe width="<!--{$width|escape:'html'|default:'425'}-->" height="<!--{$height|escape:'html'|default:355}-->" src="https://www.youtube.com/embed/<!--{if isset($playlist)}-->?listType=playlist&list=<!--{$playlist|escape:'urlpathinfo'}--><!--{else}--><!--{$id|escape:'urlpathinfo'}--><!--{/if}-->" frameborder="0" allowfullscreen></iframe></includeonly>

By default, MediaWiki provides a basic search system based on databases, which is slow and lack of features. We have installed and switched to the ElasticSearch-based search system, which is also used in Wikipedia projects in production. After that, we get the following features:

  • The search is not case-sensitive, so ‘MediaWiki’, ‘mediawiki’ and ‘MEDIAWIKI’ all give the same result.
  • We have search query suggestions, try search ‘mediawik’, see more on mw:Help:CirrusSearch#Did_you_mean
  • By default, search includes text appears in title, content, redirects
  • Use filters intitle:, incategory:, linksto: to narrow down the search fields.
  • Use prefix: to search page title

PDF Generation

Sometime it is necessary to generate office archives. At Initium Lab, we write our regular summary report on wiki and it is nice to have an offline copy of the reports. Using the browsers’ “Print to PDF” function is not flexible. In fact, Wikimedia has a dedicated project OfflineContentGeneration for generating offline files such as PDF. OCG uses LaTex to render the content and thus has a much better quality. In addition, it allows you to combine multiple pages into one coherent PDF file. You can also define custom LaTex templates, such as adding headers, footers etc.

Collaboration

MediaWiki also provides awesome features for collaboration. After all, Wikipedia is a miracle out of world-wide collaboration.

Notification

The Echo extension provides a unified notification system. User can watch pages and get notified when the page has been modified by another user. Users can also opt-in to get email notifications.

Discussion

The Flow extension provides a modern discussion page for MediaWiki. You can create a new topic, discuss with others, and archive the topic when you are done. Internally, it uses Parsoid for providing WYSIWYG editing experience. One of my favorite features is that you can finally ping another user with the dead simple @ syntax (compared to the old [[User:John Doe]] ~~~~).

Recent Changes

It is important to know what other people in the team are doing. While MediaWiki core provides a Special:RecentChanges for checking recent activities on the site, the News extension allows you to embed the recent changes in a page. At Initium Lab, we embed the News to our home page, which allows us to see what is happening on the wiki.

For encouraging user to contribute content, we also have a leaderboard page to list users with number of contributions. Currently we use the number of edits for ranking.

Structured Data

MediaWiki is firstly started to manage text. Nowadays, it can do a lot more than text. With the help of third-party extensions, we use MediaWiki to manage structured data, which allows easy data query and custom display.

Cargo and Semantic Forms

Cargo extension extracts structured information from MediaWiki templates and store them in SQL tables, and allow you to query data with SQL. For example, we ask our member to mark their leave time in a Leave template, then we can export the leave information to iCal feed and import to Google Calendar.

1
2
3
4
5
6
7
8
9
10
11
12
13
{{Leave|start=2016-05-13|end=2016-05-14|reason=Holiday}}
Caption: Put this to a User page, and you will get an entry in your Leave data table.
{{#cargo_query:
tables=Leave
|fields=name
|where=start < NOW() AND end > NOW()
|format=list
|default=nobody is on leave today
}}
Caption: Who is on leave today

The Semantic Forms makes Cargo extension more convenient. The Semantic Form can automatically generate the templates, as well as a form that can be used to edit the template. Users no longer need to deal with plain wikitext when they editing the template.

Scribunto

Scribunto, the Latin word for “they shall write”, allows to write Lua in MediaWiki pages. Lua is a script programming language that is easy to pick up. Just spend half an hour with the manual and you can start exploration. Lua is particularly helpful if you want to write complicate logic where MediaWiki’s parser functions are not enough. For example, we have used Lua to generate our iCal feed.

External Data

The External Data extension allows MediaWiki pages to retrieve, filter, and format structured data from external sources. We can also fetch external data and store them in Cargo tables. For example, we can embed the GitLab project status in a wiki page, through the GitLab API.

Extensions to Enhancing MediaWiki

Besides the above mentioned extensions, we have also installed the following extensions to enhance our MediaWiki experience:

Summary

So far, we have a great experience with MediaWiki, and we are moving more and more things to our wiki system. For anyone who is interested in trying MediaWiki, please take a look at our GitHub project. We would like to hear your thoughts.

FOOTNOTE:

知识共享许可协议
本作品采用知识共享署名 4.0 国际许可协议进行许可。