Knowledgebase
How to manage file uploads and images in MediaWiki
MediaWiki can be configured so that users are allowed to upload files by using a form on the frontend of the site. You can allow them to upload images and other file types. Images can be embedded on pages and/or links can be added to them or to other file types.
In this article we'll review some of the basic options and tasks related to file uploads. For more details check out the tutorial on how to enable, disable and manage file uploads in MediaWiki.
Enable and Disable Uploads
By default, uploads are disabled. They can first be enable during the installation of the application; there's an option available for that purpose. After that you can enable and disable uploads at any time by configuring the respective setting in the LocalSettings.php file of your MediaWiki. The option is $wgEnableUploads. Find the option in the file, and if it's set to false like this:
$wgEnableUploads = false;
this means that uploads are disabled. To enable them just replace false with true.
File Uploading
By default all registered users are allowed to upload files.
On the frontend of MediaWiki there's a form for uploading files. If uploads are enabled, it can be accessed by going to Tools menu>Upload file button, or by directly opening the URL address of the form; to do this add Special:Upload to the base URL of the site (e.g. yourdomain.com/index.php/Special:Upload).
On the form for uploading files you'll see the file types that can be uploaded and the maximum file size. To upload a file click on the Browse button and select the file you want to upload from your local computer. Then optionally you can change the name of the file as you want it to be saved and you can provide a short summary or any information about the file. There are also settings for including the file on your watchlist and for ignoring warnings during the upload. Then click on the Upload file button.
File Description Pages
When a file is uploaded MediaWiki automatically creates a description page for that file in the File namespace. If the name of the file is Example.jpg, then the full name of the page will be File:Example.jpg. It can be accessed by adding this name to the base URL of the site (e.g. yourdomain.com/index.php/File:Example.jpg). To view a full list of the files with links to the file description pages go to Tools menu>Special pages button>List of pages section>All pages button; on the page that opens select File from the drop-down menu Namespace and click on the Go button.
The page of a file can be edited as any other page and content can be added.
On the file description page you can see some information about the file: its revisions (if any), the pages that link to the file, etc. In case the file is an image you'll see a resized copy of it. If it's another file type there'll be a link for viewing the content of the file.
There you'll also find an option for replacing/overwriting the file.
Embed Images in the Content of Pages
If you want an image to be displayed on a page, edit that page and add the following:
[[File:Example Picture.jpg]]
this will embed the image Example Picture.jpg with its original dimensions. Just replace the name with the actual name of the image. In most cases you'll probably want to change the alignment of the image on the page, to resize it, etc. This can be done by adding options to the above code. It has the following syntax:
[[File:Example Picture.jpg|option|caption]]
The caption is always the last one. You can add more than one option; they should be separated with the pipe symbol |.
Some of the basic options are:
- Format - the formats that you can use are thumb, frame, frameless, border. The thumb and the frameless formats automatically resize the image using the thumbnail dimensions; in the user account settings there is an option for changing the size of thumbnails which every user can set for their account. The frameless format displays the image as it is, without any frames or borders. The thumb and the frame format show the image with a frame and if there's a caption, it's shown in the frame underneath the image. They also automatically align the image to the right; the difference between the two is that the frame format doesn't resize the image, and it is not affected by the Size option either. The border format shows the image in its original dimensions (unless a size is specifically set) and with a thin grey border.
- Size - with this option you can specify what dimensions to be used for displaying the image. For example, 200px will set the maximum width to 200 pixels. If you put just x100px then the maximum height will be set to 100 pixels. If you put 200x100px this will set both the width and the height.
- Horizontal alignment - you can set where on the page the image should be shown. You can set it to left, right, center or none.
- Link - if this option is not specifically added, each image by default is a link to its description page. With this option you can link the image to a different page on the site, to another site or you can remove the link altogether. To link to a page on the same site use the following syntax: link=Example Page. This will link to a page called Example Page. To link to an external URL use the same syntax but with the full URL address (e.g. link=http://domain.com). To remove the link simply add the option without any value (e.g. link=).
- caption - if you place a caption, it should come last after all the options. This can be any text related to the image (e.g. its name or some information about it). Just type the text after the last option. With the thumb and frame formats the caption is shown in the frame, just below the image. With those two formats you can also add links in the caption and/or format it. With the other formats the caption is shown when the mouse pointer is hovered over the image.
Here is an example with options:
[[File:Example Picture.jpg|thumb|100px|left|link=Example Page|Example caption]]
When the above is added to a page it will display the image Example Picture.jpg. The thumb format will be used and so the picture will be shown with a frame. Normally with that format the thumbnail size would be used but here the width is explicitly set to 100 pixels, so that's the size that will be used. By default, the thumb format also shows the picture on the right side of the page, but here a left alignment is specified, so the picture will be shown on the left side of the page. The image will be a link to the page Example Page on the same site, and the caption text Example caption will be shown under the image.
Insert Links to Files
If instead of embedding an image on a page you want to add only a link to that image, you can do that as well. Of course, this can also be used for file types other than images. This is done in almost the same way as embedding an image. You only have to place a colon after the first two brackets. For example:
[[:File:Example Picture.jpg]]
This will add a link to the file description page of the image Example Picture.jpg.
If you want the link to show only the image without any additional information that's on the description page, you can link directly to the image. This is done with the help of the virtual namespace Media that comes preconfigured with MediaWiki. For example, if you add the following to the content of a page:
[[Media:Example Picture.jpg]]
this will add a link to the file with the name Example Picture.jpg. When a user clicks on the link this will display a page with only the image on it. If it's another type of file, the content of the file will be shown.
User Preferences Related to Files
Each registered user can configure a couple of options related to files. The changes the user makes will be applied only to the account of the user.
To configure these options, after you log in go to Preferences button>Appearance tab>Files section on the page that opens. There's an option for setting the dimensions to be used when an image is displayed on its file description page. There's also an option for the dimensions of the thumbnail size. That's the size that will be used when the user views a page with an embedded image that's set to be displayed with the thumb format.
User Upload Permissions
By default, all registered users are allowed to upload files. The permissions related to file uploads are upload (for uploading files) and reupload (for overwriting existing uploads). These user rights are assigned to the user group (the group of all registered users), and they are also specifically added to the sysop group (the group of the administrators). If you want to remove these rights from groups or give them to other groups, you can do this by editing the LocalSettings.php file. For example, if you add the following to LocalSettings.php:
$wgGroupPermissions['user']['upload'] = false; $wgGroupPermissions['user']['reupload'] = false;the permissions will be removed from the group user, and as a result only administrators will be able to upload files and overwrite existing files. Their user group has these rights specifically enabled.
If you want to create a new group with these rights added to it, or you want to edit an existing group, put the name of the group in quotation marks in the first pair of brackets. If no such group exists with the specified name, it will be created. To add the rights replace false with true.
For more information on users and user groups read the tutorial on how to manage users, user groups and permissions in MediaWiki (or the shorter article version).
File Types
When uploads are enabled users will not be allowed to upload just any type of file. There's a list of allowed file types that can be uploaded, and there's also a blacklist with file types that are specifically forbidden. If you allow a file type but it's on the blacklist, then users will not be able to upload it. The blacklist includes file types that may potentially compromise the security of your site.
The allowed file extensions are only for the image formats PNG, GIF, JPG, JPEG. If you want to change that list and allow more extensions or remove existing ones, you can do that by editing the LocalSettings.php file of your MediaWiki. For example, if you add the following to LocalSettings.php:
$wgFileExtensions = array( 'gif', 'jpg', 'jpeg', 'txt', 'pdf' );
the allowed file extensions will be GIF, JPG, JPEG, TXT, PDF. Just list in the array the file extensions that you want users to be able to upload. If the extension is not on the blacklist it will be allowed.
Whatever changes you make, the file types that are currently allowed will be listed on the frontend form for uploading files.
Maximum File Size
The maximum size of a single file that can be uploaded depends on the set up of the hosting account. There's a PHP limit.
On the level of the MediaWiki application there's also an option for setting the maximum size of a file that can be uploaded. You can use it to change the maximum file size but it cannot be bigger than the PHP limit. The MediaWiki option for doing that is $wgMaxUploadSize. It's set in bytes. And you can add it to the LocalSettings.php file of your MediaWiki. For example, if you add the following:
$wgMaxUploadSize = 1024 * 1024 * 3;
this will set the maximum upload size to 3145728 bytes (3 megabytes). You can set it in the way shown above so that it's easier to know what the size is in megabytes: the number of bytes in a kilobyte (1024) multiplied by the number of kilobytes in a megabyte, multiplied by the number of megabytes.
File Uploads Folder
The uploaded files are stored in a folder labeled images on your MediaWiki hosting account. That folder is in the root MediaWiki directory. For example, if the application is installed directly in the public_html directory, the path to the folder will be public_html/images. MediaWiki automatically creates a subdirectory structure within the images folder. Each image is saved two levels down, meaning in a subfolder of a subfolder of the images folder (e.g. public_html/images/a/a9/Example.jpg).
Delete and Undelete Files
One way to delete a file is to delete its file description page. This is done in the same way as deleting any other regular page. By default only sysops/administrators are allowed to do that.
On the file description page there's a table that shows the revisions of the file. If different versions of the file have been uploaded, they'll be listed in that table. There's delete button for each version. If you delete all versions, or there's only one and you delete it, this will have the same result as deleting the page. It will remove the file.
Deleting a file like this doesn't permanently remove it, and it can be restored. This is done in the same way as restoring a deleted page. You can do it either from the Recent changes page, or from the Deletion log (Tools menu>Special pages button>Recent changes and logs section>Logs button).
You may also find useful the following articles related to uploaded files and images: