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.
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
sysopgroup can create new account
- Anonymous users cannot view or edit any page (with exceptions such as the user login page)
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.
For the details of user rights management, please check the MediaWiki documentation.
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.
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.
[[/Python/]] to link to the Python subpage. Check subpage help for details.
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.
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.
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
linksto:to narrow down the search fields.
prefix:to search page title
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.
MediaWiki also provides awesome features for collaboration. After all, Wikipedia is a miracle out of world-wide collaboration.
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.
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]] ~~~~).
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.
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 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.
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, 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.
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.
Besides the above mentioned extensions, we have also installed the following extensions to enhance our MediaWiki experience:
- RandomSelection: Provides Did You Know function.
- WikiEditor/VisualEditor/CodeEditor to provide better wikitext editing experience
- InputBox to provide a nice search box on the home page.
- ReplaceText to search and replace multiple text occurrence at once
- UploadWizard provides better upload experience (AJAX based, multiple files at the same time, etc)
- Gadgets to embed additional JS/CSS in the system. Check https://en.wikipedia.org/wiki/Special:Gadgets for the gadgets installed on English Wikipedia.
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.
-  Figure for May 2016, Source: https://stats.wikimedia.org/EN/TablesPageViewsMonthlyCombined.htm, ↩