Configuring MediaWiki for Images

This article describes how MediaWiki stores images; how to configure MediaWiki to change how images are stored; and how to allow or disallow specific file formats.

MediaWiki and Images

When adding an image to a MediaWiki it is common practice to select and upload an image and insert it in a page in one fluid sequence.

It is also fairly simple to find a previously uploaded image and include it on a page.

To get an overview of the images in a MediaWiki site open the Tools Menu --> Special Pages scroll down to either Gallery of new files or File list.

By default, MediaWiki stores uploaded files and images in the /w/images folder.

When you upgrade the version of a MediaWiki installation the contents of /w/images will need to be copied to the new version.

That is when you may also notice that /w/images is full of sub-directories each containing only one or two files, and your image library has no obvious stucture. Like the screen grab shown on the right.

Allowed File Formats

$wgFileExtensions MediaWiki supports file formats .jpg or .jpeg, .png, .gif and .webp by default. If you intend to use other file formats such as .svg or the .pdf the default array of allowed file extensions can be extended by merging a new array, but it is simpler to add one at a time:
```
$wgFileExtensions[] = 'svg';
$wgFileExtensions[] = 'pdf';
```
For the mh370wiki.net website I added $wgFileExtensions = array( 'png', 'gif', 'jpg', 'svg', 'pdf' ); This has the effect of over-riding the default array of allowed file types, replacing it with my limited set of five file formats. If I need to add another one I will just alter my custom array in LocalSettings.php.

How and Where does MediaWiki store Images and Files

$wgEnableUploads In LocalSettings.php enable image uploads with the setting $wgEnableUploads = true;

$wgUploadPath The relative path to the directory where images (and files) will be stored. By default, this is /w/images. More accurately, this is $wgScriptPath/images. In LocalSettings.php this normally defined as shown below, and the upload path does not need to be defined unless it is changed.

## The URL base path to the directory containing the wiki;
## defaults for all runtime URL paths are based off of this.
## For more information on customizing the URLs
## (like /w/index.php/Page_title to /wiki/Page_title) please see:
## https://www.mediawiki.org/wiki/Manual:Short_URL
# Default Configuration
$wgScriptPath  = "/w";
$wgArticlePath = "/wiki/$1";

Note: If the /wiki is removed from the URL, like this website, the ScriptPath remains "/w" but the ArticlePath changes to $wgArticlePath = "/$1";

$wgUploadDirectory The directory where files are uploaded to. By default, this is {$IP}/images. IP is an abbreviation of Install Path and is configured as MediaWiki is installed.

$wgHashedUploadDirectory
1. $wgHashedUploadDirectory='true'; Enabled by default and is the cause for the strange way MediaWiki stores images. Here is the official explanation:-
```
If true, uploaded files will be distributed into sub-directories of $wgUploadDirectory based on the first two characters of the md5 hash of the filename. (e.g. $IP/images/a/ab/foo.jpg) Creation of such subdirectories is handled automatically. This is used to avoid having too many files in one folder because some filesystems don't perform well with large numbers of files in one folder.

The algorithm for that is based on a md5 of the name, the first hex character is used for the first directory, then the first two characters are used for the subdirectory.

    Foo.png → md5 of filename = f865cbca12286c1c5b7616b4a70fbf68 → f + f8 = $IP/images/f/f8/Foo.png
```
2. $wgHashedUploadDirectory='false'; To override the default state, add this to LocalSettings.php.
  If $wgHashedUploadDirectory='false'; then all images will be uploaded into the $wgUploadDirectory. Although 'neat', apparently 'some filesystems don't perform well with large numbers of files in one folder'.
3. Changing $wgHashedUploadDirectory='true'; to $wgHashedUploadDirectory='false'; This creates another problem - articles containing images will not display the image because it cannot be found. For example, the screen grab of the /w/images sub-directories on this page was saved and uploaded as ImagesFolders.jpg and to include it on this page (ignoring float:right) is simply
```
[[File:ImagesFolders.jpg]]
```
  The path to the file is not needed because it is calculated (using the md5 of the file name) and the $wgUploadPath.
  The existing images in all the sub-directories would need to be moved to the parent directory /w/images.

Images and Files on the mh370wiki.net website

To avoid potential issues with the way MediaWiki stores images and files, and to retain a directory structure of my own, I set $wgAllowExternalImages=true; in LocalSettings.php and now store all files and images external to the MediaWiki installation.

To be more precise, I have a folder on my home PC which contains all the images and files currently in use by the mh370wiki.net website (Master). On my remote site, in the /home directory provided by the Hosting service, I have a directory which contains the same images and files, in the same directory structure (Copy).

When I want to add an image or file to the website I first copy it to the local Master folder, then use FTP to transfer the image(s) or file(s) from the local Master to the remote Copy folder.

There are several hundred images and about two hundred files currently uploaded and available for use by mh370wiki.net.

The directory structure is quite logical, with parent directories for Images and Files containing subdirectories named by topic or file-source.

When I am editing a page and need a path to an image I can easily locate the local Master copy, and use the local directory structure as the path, because the remote Copy structure is the same.

Some extra information

A .htaccess file is placed in the root directory of the remote Copy folder to prevent unauthorised access.
The remote Copy folder is located in the /home directory but outside of the public_html directory.
I use a sub-domain as the URL for the images and files, so the path is like this: sub.mydomain_name/Copy_folder/Images/sub-directory/filename.
When upgrading MediaWiki I do not need to copy the /w/images folder.
When creating a backup copy of my MediaWiki installation I do not need to include all the images and files which would be in the /w/images folder.
I can keep previous versions of the website just as they were prior to an upgrade, without the need to replicate the /w/images folder in each installation.
I also have an FTP-enabled folder in my /home directory, to which I can upload images or files and then, as a second step, copy the image or file to the relevant Copy directory. But copying files using File Manager in cPanel is a bit awkward.
I have been using this system for over five years. When I changed the website URL by removing /wiki I had to update all the file paths but by then the tool Special Pages --> Replace text was working well and made the transition easier.

Links

Help:Images: https://www.mediawiki.org/wiki/Help:Images
Manual:Image administration: https://www.mediawiki.org/wiki/Manual:Image_administration
Manual:Configuring file uploads: https://www.mediawiki.org/wiki/Manual:Configuring_file_uploads