Working with MediaWiki
2nd ed., HTML version

Chapter 7 Images and files

MediaWiki should never be mistaken for a real document-management system, but it does have a reasonable amount of support for managing files. True document-management systems have integration with the file system of the computer or network they're on, and usually let you edit documents inline – neither of which MediaWiki allows. (Though there's discussion about enabling the latter for MediaWiki, for SVG and some video formats, in the future.) MediaWiki does, however, let you upload files, and display them within other pages in a variety of ways – and it keeps a version history for each file, which is a very useful feature.


The standard interface for uploading files to MediaWiki is the page Special:Upload, which lets you upload one file at a time.
Figure 7.1: Special:Upload page
When you upload a file, you are asked to select its name on the wiki, which, by default, is the file's name on the local system. You can also provide a summary of the file, and finally you are asked to specify a copyright type for that file, based on the set of allowed copyrights for the wiki (more on this later). The copyright choice assumes that the person doing the uploading was responsible for generating the file; or, at the very least, knows the copyright wishes of the person who generated the file – and often, neither of these is the case. This book will not get into issues of copyright, legal or otherwise; but you should know that there are a lot of options for allowed copyright type, and the best solution may depend on a variety of circumstances, including whether the wiki is public or private.
Once a file is uploaded, several things happen: the file gets placed in the wiki's images/ directory (the directory is called “images”, even though it can hold uploaded files of all types); a page in the “File:” namespace is created for that file (the full name of the page will be “File:page-name”, like “File:Cat.png”); and, if it's an image, and the image is bigger than the standard thumbnail size, a thumbnail is created for that file and is placed in the directory /images/thumb.

The images/ directory

The images/ directory can take two structures. By default, the directory is subdivided into two levels of subdirectories, where the first level consists of folders whose name is a single hexadecimal digit, from “0” to “f”; and the second level has folder names whose name consists of the parent folder's number or letter, plus a second hexadecimal digit. In other words, a file can be placed in a directory like “/images/8/8b” within the MediaWiki directory. There are 16 * 16 = 256 such possible sub-subdirectories. This default approach is also known as the “hashed” approach. It is used to try to prevent directories from getting too large – some file systems have a limit on the number of files any one directory can contain.
The other approach is to simply store every file in the images/ directory. This approach has the advantage of simplicity, and for smaller wikis it's just as good a solution. To enable this approach, add the following to LocalSettings.php:
$wgEnableHashedUploads = false;


A thumbnail is a small image meant to represent an uploaded file. For files that are images, these are simply smaller versions of the original image (or, for images that are already small, versions of the same size). For non-image files, these tend to just be an icon: for PDF files, for instance, it's the Adobe Acrobat logo.

Troubleshooting uploading

It could be that, when you go to upload files on a wiki, you find that you're not able to do it. That could be for any of the following reasons:
If it looks like PHP is blocking uploads, add the following line in php.ini:
file_uploads = On
If the images directory is not writable, the solution depends on the web server and file system in question – this page holds more information:
Uploading also needs to be enabled in MediaWiki itself – make sure that you have the following line in LocalSettings.php:
$wgEnableUploads = true;
By default, every logged-in user is allowed to upload files, but unregistered users aren't. This can be changed in LocalSettings.php, via the 'upload' permission. (There's also a second relevant permission type, 'reupload', for uploading files that already exist on the wiki and thus overwriting their contents.) To prevent regular users from uploading, for instance, you could add the following to LocalSettings.php:
$wgGroupPermissions['user']['upload'] = false;
$wgGroupPermissions['sysop']['upload'] = true;
And it may be that you're allowed to upload files in general, but the specific file you have can't be uploaded. That could be for two reasons: the file's size, or its file type.
Every wiki has a limit on the allowed size of uploaded files, which is set by a combination of four PHP and MediaWiki settings. Essentially, the smallest of these dictates what is allowed to go through, so you may need to change all four to increase the allowed limit on file sizes. There are two PHP settings: “post_max_size” and “upload_max_filesize”, both of which would need to be changed in php.ini. The two MediaWiki variables are $wgUploadSizeWarning and $wgMaxUploadSize – both represent a number of bytes. $wgUploadSizeWarning sets only what file size results in a warning to the user, so it doesn't actually affect which files go through and which don't – but it should be made consistent with what the actual limits are. So, to change the allowed file size to 30 megabytes, you would change the following in php.ini:
post_max_size = 30M
upload_max_filesize = 30M
...and add the following to LocalSettings.php:
$wgUploadSizeWarning = 30 * 1024 * 1024;
$wgMaxUploadSize = 30 * 1024 * 1024;

File type restrictions

What if someone tries to upload a .doc file simply by renaming the file's extension to, say, “.gif”? Thankfully, MediaWiki guards against that by looking at the file's internal file type, which the web server determines – the allowed set of file suffixes is really just shorthand for the allowed set of file types.
To add to or change the allowed set of file types, use the “$wgFileExtensions” variable in LocalSettings.php. The most common addition is allowing PDF files – to do that, you would add the following line:
$wgFileExtensions[] = 'pdf';

Extensions for uploading

MsUpload is a popular extension that displays, in conjunction with the WikiEditor extension (here), a button that makes uploading a file and displaying it on a particular page easy to do:
Finally, uploads are possible via Page Forms. Uploading from within a form has the advantage that the name of the file gets automatically placed on the page after it's uploaded, so that users don't need to do the second step of inserting a tag to display the image/file on the wiki page after they've uploaded it. For more on this option, see here.

Displaying images

Images are generally displayed by simply linking to the image – which is a somewhat unexpected syntax. Let's say there's an image on the wiki called “Easter Island.png”. The simplest way to display it is to just have the following:
[[Image:Easter Island.png]]
Alternatively, you could have this instead, since “Image” and “File” are aliases for the same namespace:
[[File:Easter Island.png]]
For the rest of this example, we'll just use “Image”.
There are various additional settings you can apply to images: the height and width, the horizontal and vertical alignment, the caption, where the image links to, whether to place a border, etc. These are all parameters that can be added to the image tag, separated by pipes. Some are named, while others are unnamed.
Here's an example of an image display with more parameters set:
[[Image:Easter Island.png|100px|x150px|right|link=Easter Island info|This is Easter Island.]]
The parameters can be passed in in any order, so the parser determines what parameter each value corresponds to, based on the specific text in each (except for a few named parameters like “link=”). A “px” value without an “x” at the beginning sets the width, while one with an “x” at the beginning sets the height. “right” here controls the horizontal alignment of the image – the other options are “left”, “center” and “none”.
The “link=” parameter sets the location that the image links to – it can be either a wiki page or a URL. By default, an image links to its own page.
The last parameter, unless it's obviously something else, sets the caption for the image.
What if you just want to link to an image, rather than display it? You can either link to the wiki page for the image, or to the image itself. To link to the image's wiki page, just add a colon at the beginning of the link, so it looks like:
[[:Image:Easter Island.png]]
If instead you want to link directly to the image, use the “Media” namespace instead, which exists just for this purpose. You could do:
[[Media:Easter Island.png|Click here to see a great picture.]]
There's more customization that can be done of image display. This page has all the details, as well as a lot of helpful demos:

Image galleries

The built-in MediaWiki tag <gallery> lets you display a group of images in one place. It takes in a group of image names and, optionally, their captions (which can include wikitext); a call to it would look like the following:
Image:Rhesus monkey.jpg|This is a [[rhesus monkey]]
Image:Large monkey.gif|This is a ''large'' monkey
Newlines here separate the names of the images.


You can also display images in a JavaScript “slideshow”, which is an interface where a series of images and/or text appear one after another in the same spot. The switching from one display to the next can be done manually, using links or arrows so that the user can flip through the images, or by simply cycling through them automatically. There are several extensions that do this; the most reliable standalone extension currently seems to be JavascriptSlideshow, which also lets you include text within each slide:
This slideshow functionality should not be confused with a PowerPoint-style slideshow presentation. There actually is an extension that lets you turn wiki pages into individual slides, suitable for a presentation – S5SlideShow:
The capability to run a slideshow presentation directly from the wiki is nice, because it lets you create a presentation collaboratively, in the manner of Google Docs.

Audio and video

You may want to let users upload and view audio and video files directly in the wiki, rather than using outside services like SoundCloud or YouTube. You can do that with the TimedMediaHandler extension, which uses VideoJS, a popular open-source JavaScript library, to display both audio and video files. One nice aspect of TimedMediaHandler is that you don't even have to call a parser function: you can simply use the standard “File:” syntax, like [[File:Fishing tutorial.ogv]], and a video or audio player will be displayed for that file. The supported formats include Ogg and its variations, as well as MIDI and the better-known MP3 and MP4/M4A.
For more information, see:

Displaying outside images

By default, images from outside the wiki cannot be displayed. That's for several reasons, the most important of which is that a malicious user can place an external image on a wiki page, then collect information about all the visitors to that page; which would be a violation of privacy. You can change this default by adding the following to LocalSettings.php:
$wgAllowExternalImages = true;
If this is set, placing the URL of an external image in a page will display that image there.
You can also, instead, use the variable $wgAllowExternalImagesFrom to only allow images from certain trusted domains. Here is one example:
$wgAllowExternalImagesFrom = ['', ''];
$wgUseInstantCommons = true;

Displaying PDF files

This is one of the extensions that comes bundled in with MediaWiki.