How To Customize MediaWiki Using the LocalSettings.php File
Introduction
MediaWiki is an open source wiki application that allows you to create your customizable wiki sites. Originally developed by the WikiMedia Foundation to serve the needs of Wikipedia, it can be adapted for individuals and smaller organizations.
This guide assumes that you have installed MediaWiki on your VPS and have completed the initial configuration steps with your web browser. If this is not the case, please follow the instructions here to install MediaWiki.
In a previous guide, we installed MediaWiki on an Ubuntu 12.04 installation. In this article, we will go over some basic configuration that can be done through the LocalSettings.php file.
Can You Edit Preferences Through the Web Interface?
Although many preference changes and site management tasks can be administered through the normal wiki web interface, there are some changes that require editing text files on the server.
The LocalSettings.php file is not accessible from the web interface as a security measure. To edit the file, SSH into your VPS in order to edit this file manually.
Where Does MediaWiki Store Default Values?
Default settings are kept in a file called DefaultSettings.php.
You should never edit DefaultSettings.php, but looking at it can be very valuable. Since we will not edit the file, open it in a pager:
less /etc/mediawiki/includes/DefaultSettings.php
If you see a value in this file that you wish to change, take note of it. Later, you can add the value to the LocalSettings.php file.
How Do You Edit Default Values?
Configuration should be done in the LocalSettings.php file. It looks very similar to DefaultSettings.php, but is shorter. Type the following command to open the file for editing:
sudo nano /etc/mediawiki/LocalSettings.php
This file is written in the PHP programming language, but the syntax is relatively easy to understand. For the most part, you will see the following syntax:
$VariableName = "VariableValue";
This file has many different configuration settings, but not all of the available settings are defined here. Generally, only those settings with values that contradict the defaults found in DefaultSettings.php are found here.
If you wish to change the settings of anything found in DefaultSettings.php, look for the variable in LocalSettings.php. If it does not exist, add it to the bottom.
Common Configuration Settings
Before making any changes, go ahead and backup the configuration file in case something does not work as expected:
sudo cp /etc/mediawiki/LocalSettings.php /etc/mediawiki/LocalSettings.php.bak
Reopen the LocalSettings.php file to edit the following values.
sudo nano /etc/mediawiki/LocalSettings.php
How To Change the Site Name
You selected a name for your site during initial configuration. You can change your site's name by editing two variables: wgSitename and wgMetaNamespace.
$wgSitename = "New Site Name"; $wgMetaNamespace = "New_Site_Name";
The second variable sets namespace for the pages that refer to the wiki itself. It cannot contain spaces, so we use underscores instead.
How To Change the Site Language
If you need to change the language encoding of your site, you can modify the value of the wgLanguageCode variable:
$wgLanguageCode = "language_code";
The "language_code" in this instance refers to any value defined in this file:
less /etc/mediawiki/languages/Names.php
After changing the language, you need to run a script to implement the change:
cd /etc/mediawiki/maintenance
sudo php rebuildmessages.php --rebuild
How To Allow Image Uploads
Before we allow image uploading on the wiki, we want to install some additional image-handling software from the "imagemagick" suite:
sudo apt-get install imagemagick
Reopen the LocalSettings.php file.
sudo nano /etc/mediawiki/LocalSettings.php
To allow your wiki's users to upload their own images to pages, you can change the wgEnableUploads variable to "true":
$wgEnableUploads = true;
Uncomment the next two variables to configure MediaWiki to use imagemagick for image resizing, converting, and manipulating.
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";
These settings will enable the ability to use thumbnail images for user uploads.
By default, these settings allow for uploads in "png", "gif", and "jpeg/jpg" formats. If you would like to allow additional formats, add the wgFileExtensions variable to the bottom of the file like so:
$wgFileExtensions = array( 'png', 'gif', 'jpg', 'jpeg', 'pdf', 'additional_format', '...')
Note: Any website that accepts content from users is adopting a certain level of risk! Be sure that you are aware of the implications of allowing user uploads and take the appropriate steps to mitigate these dangers.
How To Allow WikiCommons Images
An additional variable that you may wish to set to "true" is wgUseInstantCommons.
This allows your wiki to automatically configure access to content in Wikimedia Commons. These can be incorporated into your own pages.
$wgUseInstantCommons = true;
To use images from Wikimedia Commons, find an image you'd like to use at:
http://commons.wikimedia.org/
Navigate to your image. In the URL, copy from File: to the end of the URL.
Now, open or edit a page, and simply paste what you've copied within double brackets
[[File:Parson_Russell_Terrier_Puppy_3_Months_Old.jpg]]
The image will be available on your page.
If you wish to make a thumbnail instead, follow the filename with a pipe character (|) and "thumb".
[[File:Parson_Russell_Terrier_Puppy_3_Months_Old.jpg|thumb]]
The WikiMedia image will show up on your wiki:
How To Change the Wiki Logo
One commonly requested piece of information is how to change the logo in the upper-left corner of the page to something relevant to your site.
By default, the wiki page displays the following image:
First, copy the file you want to act as your logo into the appropriate directory on your VPS:
scp /path/to/local/image.png username@server_ip:/etc/mediawiki/skins/common/images/
Now you have the image on your wiki server. Change the path of wgLogo to reflect the image name:
$wgLogo = "$wgStylePath/common/images/image_name.png
Your logo will now replace the former message.
How To Configure Email Options
To receive administrative emails, including bug reports, include your email after the wgEmergencyContact variable.
$wgEmergencyContact = "your_email@address.com"
You will also want to configure the wgPasswordSender email to point to an actual email address, so that users can respond to the email if they have problems.
$wgPasswordSender = "password_email@address.com"
Conclusion
You should now know how to configure some common settings located within the LocalSettings.php file.
There are many, many configuration settings available for MediaWiki that are not present in LocalSettings.php by default. Remember to read the default settings file located at /etc/mediawiki/includes/DefaultSettings.php to discover more configuration options. The file is well-commented. More information on specific variables can be found here.
5 Comments