Table of Contents
If you stumbled upon this post, chances are you just installed your very own MediaWiki and want to make it prettier. That's completely understandable since the default MediaWiki installation, with its starting set of starting extensions, modules and templates, isn't that fancy: you can do titles/headers, make your text bold and/or italic, create wikilinks and hyperlinks and that's about all.
Owning your very own MediaWiki is fun, but if you've choose MediaWiki over the other great alternatives out there - such as TikiWiki, for example - it means that you want it to look just as fine as Wikipedia - or any other professional-looking wiki - actually does. In order to do that, you will have to install quite a number of additional stuff. This article, as well as many others I'll be publishing during the next weeks, will teach you how to do that.
If you didn't do that already, I strongly suggest to start with replacing the default MediaWiki editor with the WikiEditor: we already explained how to achieve that with this post.
Right after that, a great improvement you might want to accomplish could most likely be something like the following:
Yeah, we're talking about that fancy informative Message Box out there explaining that the article needs additional citations. As you might already know, this is a template, one of the greatest feature of MediaWiki. A template is basically a standard piece of content that can be included on several pages, providing an easy interface to slightly change its text (or images, or behaviour) to match the page in which you're using it. As a matter of fact, working with templates will save us a lot of work, because we'll be able to reuse indefinitely the most of what we did without having to reinvent the wheel everythime.
Understanding Templates
Does that mean we have to design this template manually? Luckily enough, we don't have to: as a matter of fact, MediaWiki templates can be exported and imported between different MediaWiki installations, meaning you will be able to use Wikipedia's templates in a matter of minutes without having to design them from scratch. However, before doing that, there are a couple things to learn about how these templates actually work.
How Templates work
The easiest way to learn how MediaWiki Templates actually work is to create your own template. Open your MediaWiki and create a new Template:MyFirst page with the following contents:
|
1 |
''Hi! This is my first template.'' |
Then create another page, calling it MyFirstTest, and type in the following contents:
|
1 2 3 4 5 6 |
Hello, this is a page meant to test the '''MyFirst''' template. Here it is: {{MyFirst}} Pretty neat, isn't it? |
Right after that, take a look at the page you've just created. You should see something like the following:
That's how template works. For further info regarding them, including how to properly use template variables, I strongly suggest you to read this MediaWiki official page.
Advanced Templates
We won't dig too much into the most advanced concepts of templates: for the sake of simplicity, we'll just highlight the following core concepts we need to know before importing them:
- A template can include other templates, meaning that we could create a Template:MySecond and add a reference to {{MyFirst}} in its contents, just like we did with the MyFirstTest page. This behaviour is so much used on wikis such as Wikipedia that a lot of templates are in fact Metatemplates, which is a term used to refer to a back-end template used by other front-end templates only.
- A template can pass one or more variables to metatemplates, meaning that we can "expose" some of the Metatemplate variables through a front-end template, thus making it more versatile: we can also provide some default values for these variables if the user doesn't give them an explicit one.
- A template can invoke extensions, including those enabling the usage of functions (ParserFunctions) and/or modules (Scribunto). This is the most advanced - and powerful - template usage, as it allows to use scripting languages (such as LUA) within MediaWiki, thus enabling an endless amount of features for any template.
Again, if you want to know more about advanced templates, I suggest you to read the MediaWiki official documentation. For now we're going to stick to our original topic, which is how to import Wikipedia templates into our own MediaWiki installation.
To-do list
After the much needed introduction, it's time to make a quick list of what we're going to do in order to achieve our task:
- Upgrade our MediaWiki to the latest stable version, hoping to match Wikipedia's one.
- Install the Scribunto extension and properly configure it.
- Export/Import the LUA modules used by the (meta)templates you want to use and import them in your MediaWiki.
- Export/Import the Wikipedia templates you want to use, together with all the required metatemplates, and import them in your MediaWiki.
- Copy the relevant CSS classes from the Wikipedia's Common.css file and paste them in your MediaWiki's Common.css.
- Activate MediaWiki IstantCommons feature to automatically fetch the Template image files from the commons.wikipedia.com repository.
That's about it: are we ready to start?
Upgrading our MediaWiki
If we want to use Wikipedia templates, we have to be sure that our MediaWiki installation will be able support them. MediaWiki happens to be a moving beast, with many updates each year, and their templates are also nothing less than that. The Wikipedia engine, being the core reason for the MediaWiki project existence, always gets updates as well, and their templates code will do the same: to keep it simple, if you want to use their stuff you need to be just as updated as they are.
You can check the current Wikipedia version by taking a look at the following page:
Before upgrading your build to match it, you're free to check the changelog to see if there are breaking changes with the latest stable version, including the most relevant extensions: if there are none, you could try to keep yours, otherwise you have to upgrade. Needless to say, you are forced to do this only the first time: once you import the templates, you are free to stay behind... until you'll need to import more templates!
To upgrade your MediaWiki installation you can either get the latest snapshot for the build you're looking for or download the full package from the official download page. I strongly suggest to do the latter, since you'll also get the bundled extensions and styles (they will need to be upgraded too) without having to get them manually.
The upgrade instructions can be very different depending on what build you already have and/or the one you're upgrading to. As a general rule, don't underestimate the MediaWiki upgrade process. This is not an easy software, and it most likely won't be a matter of seconds like most other PHP applications are these days. You will have to closely follow the instructions or you will break your environment for good: you could also be asked to run PHP scripts from the command-line (using the PHP Command-Line Interface), alter your current database schema, upgrade third-party software libraries such as ImageMagick, Python, GhostScript and maybe even your core PHP build.
Needless to say, it's imperative to backup either the MediaWiki installation folder and the Database before starting the process: if you skip that, there are high chances that you'll regret that choice.
Installing Scribunto
Scribunto (they shall write in latin) is a revolutionary extension that allows MediaWiki editors to embed one or more scripting languages in MediaWiki. Currently the only supported scripting language is Lua, which happens to be an awesome choice for a number of good reasons: easy and friendly syntax for non programmers, fast performances (with the JIT-compiler), well-documented, simple yet powerful debug features, great community support. It has it downsides too, but nothing that truly impacts the usage on MediaWiki.
To install and configure Scribunto, just download it from this official Wikipedia ExtensionDistributor Page. Be sure to select the right version of MediaWiki: you need to pick the one matching your installed one (or lower): if you are unsure about it, go to the /Special:Version page of your MediaWiki and look right below the Installed Software header. Once you got the extension, unpack it into the /extensions/ folder of your MediaWiki installation.
This is what you need to have at the end:
|
1 |
<mediawiki_folder>/extensions/scribunto/<scribunto_files> |
Once done, open your LocalSettings.php file and add the following line at the end of the already referenced extensions, i.e. the lines starting with
wfLoadExtension
:
|
1 2 |
require_once "$IP/extensions/Scribunto/Scribunto.php"; $wgScribuntoDefaultEngine = 'luastandalone'; |
If you're using the MediaWiki's SyntaxHighlight extension (more info here), you might also want to add the following line to highlight the Lua source code within the various modules:
|
1 |
$wgScribuntoUseGeSHi = true; |
That's it.
Exporting/Importing Modules
Now that our MediaWiki has Scribunto, it can support LUA modules. This is a list of the modules we need to import the informative message box template from Wikipedia we've seen at the start of this post, which by the way is called Refimprove and is built upon the Ambox metatemplate, which is built upon the Message box module (and so on: you're starting to understand why we have to do all this, aren't you?).
Here's a list of the modules that we need:
- Module:Message_box
- Module:Message_box/configuration
- Module:No_globals
- Module:Category_handler
- Module:Yesno
To export them, go to the Wikipedia export page and manually add them all to the big, multi-line "Add pages manually" textbox, just like that:
Be sure to select the three checkbox, including the include templates one, which is often unchecked by default, then click the Export button. An XML file will be generated and made available for download: save it on a temporary folder, then open another tab on your browser and connect to the Special:Import page of your MediaWiki installation.
Once there, import the previously downloaded file selecting the "Import to default locations" radio button among the self-excluding possible choices.
Exporting/Importing Templates
Now that we have the modules, we need to do the same with the templates. Go back to the Wikipedia export page and type the following in the "Add pages from category" textbox:
- Category:Mbox_and_messagebox_templates
As soon as you click the Add button, the textbox below will be filled with the templates taken from that category. Go back to the upper textbox and repeat the same task by typing the following:
- Category:Article_message_templates
Another streak of templates will be added as well. That's all we need to properly support the Refimprove template - as well as hundreds of other similar ones.
Again, click the Export button and save the XML file locally. Once we do that, we can go back to our MediaWiki Special:Import page and import the templates just like we did with modules a short while ago.
Copying CSS Classes
To ensure that our message box will be have the exact same look & feel they have on Wikipedia, we need to copy the relevant parts of Wikipedia's MediaWiki:Common.css special page into your wiki page of the same name. We can see the required classes by looking at the Module:Message box/configuration code and figure them out: or, as a viable alterrnative, we could just copy the whole Wikipedia's MediaWiki:Common.css content into ours: it won't affect our MediaWiki look and feel in any way, unless we already skinned something differently.
Activating IstantCommons
The last thing we need to do is to activate the Wikipedia's IstantCommons feature, so the required image files will be automatically fetched from the commons.mediawiki.com centralized repository: if you want to know more about IstantCommons, you can read this article for additional info.
Since the release of MediaWiki 1.16, enabling the IstantCommon feature is just as easy as adding the following line to our LocalSettings.php page:
|
1 |
$wgUseInstantCommons = true; |
Troubleshooting
Here's a brief list of the most common issues that could happen to you during the aforementioned steps and some suggestions about how to fix them.
Importing issues
If you get errors such as these while importing your exported XML file(s) via your MediaWiki's Special:Import page:
|
1 2 |
Warning: XMLReader::open(): Unable to open source data in /.../wiki/includes/Import.php on line 53 Warning: XMLReader::read(): Load Data before trying to read in /.../wiki/includes/Import.php on line 399 |
And the POST response received after the upload shows the following error:
|
1 |
Import failed: Expected <mediawiki> tag, got <anything> |
It's most likely due to the fact that the libxml extension and/or the PHP entity loader crashed and went on a unrecorevable state across the entire web server, thus preventing any import from complete successfully. This was a common issue on MediaWiki builds up to 1.26, however it can still happen if you have multiple PHP websites configured on your machine. The most secure fix is to restart the webserver service, so the libxml will be restored to a working state.
More info on this issue can be found here (PHP entity loader bug) and here (MediaWiki's Phabricator task).
LUA errors
If the imported LUA modules don't work and/or are showing errors, the most common cause is due to the fact that either MediaWiki and/or the Scribunto extensions are not up-to-date and/or differ from the current Wikipedia build. To fix these issues, you can do the following:
- Upgrade your version(s) of MediaWiki and/or Scribunto.
- Manually copy a previous version of the module source code on Wikipedia that was written against a previous MediaWiki build (matching yours).
You can also try to fix/troubleshoot the issue by yourself by activating the LUA error log. To do that, add the following line in the LocalSettings.php file, right after the Scribunto extension loading command:
|
1 |
$wgScribuntoEngineConf['luastandalone']['errorFile'] = 'lua_error.log'; |
Well, that's it for now: happy configuration!
First, let me thank you for this wonderful tutorial. I struggled a bit but ended up getting through every step.
For others who are journeymen like me (not super admins), here’s some hints to make your life easier.
1) Make sure lua51 is installed on your system. Once it is, add these two lines to LocalSettings.php:
$wgScribuntoDefaultEngine = ‘luastandalone’;
$wgScribuntoEngineConf[‘luastandalone’][‘luaPath’] = ‘/usr/local/bin/lua51’;
If you don’t do this, the import step that fetches the Templates will fail.
Once you’ve done that you may find, like I did, that the import times out. If it does, make a copy of the export window on Wikipedia and paste it into a text file. Then make smaller sections with less templates and import those. I found that about 1.4MB was the largest size that would import before it timed out. (Note: there may be a setting that would overcome this, but I have no clue what it would be.)
If you run into problems and the cryptic error messages aren’t helpful, add this line to LocalSettings.php: #$wgShowExceptionDetails = true;
Make sure you comment this line out once you get things working. You don’t want site visitors seeing this level of detail should something error out.
Now, my question for Ryan. How the heck do I get the link to Cite to show up in the WikiEditor? I’ve Googled my eyeballs out to no avail. I thought your tutorial would be the answer, but I still don’t have that dern link to Cite (like Wikipedia has).
I’m setting up a wiki for old men. I need that link.
Thank You So Much for this guide! I scavenged the web and worked for hours and nothing was this easy to follow!! Thanks again!!
Glad you liked it! Thank you for writing this :)
This looked like it would help me, but it does not.
3 problems
one of the export-import does not work, something to do with Linux and the binary not being an executable.
copying the CSS from Wikpedia results in a HTPP 500 error and no explanation
running the example code: it just displays: Template:infobox and nothing else.
Where do I begin to make this right?
Hello here,
you should be more specific, because with this kind of info we are definitely unable to help.
1) Which export-import did not work? What’s the exact error message and from what platform (wikipedia or your mediawiki instance)?
2) Copying the CSS is a plain and simple cut and paste operation, it cannot produce a 500 error unless there are some serious installation and/or configuration issues in the mediawiki installation itself. It’s very likely that such issue is also the main cause of errors #1 and #3 as well.
3) What “example code” are you talking about? Did you check the LUA error log file? Anything useful there?