Skip to content

MediaWiki Image & Media — File Uploads, Galleries, Thumbnails, and Media Settings

DodaTech Updated 2026-06-26 10 min read

In this tutorial, you will learn about MediaWiki Image & Media. We cover key concepts, practical examples, and best practices to help you master this topic.

Managing images and media files on your MediaWiki wiki means uploading files, controlling display with thumbnails and galleries, configuring allowed file types, and organizing media assets — skills every wiki administrator needs when creating illustrated documentation like Wikipedia articles with embedded images.

What You'll Learn

  • Uploading images and files to your wiki
  • Displaying images with thumbnails, frames, and captions
  • Creating image galleries
  • Configuring file upload settings (types, sizes, permissions)
  • Using the File namespace for media organization

Why It Matters

A wiki with only text is a wiki nobody wants to read. Images explain concepts faster than paragraphs. Screenshots guide users through software. Diagrams visualize architecture. Logos and icons build brand identity. MediaWiki's image system gives you precise control over how media appears without writing HTML, and the File namespace tracks every version of every file.

Real-World Use

A DodaTech product wiki includes screenshots of each configuration step, a logo at the top of the main page, architecture diagrams in technical specifications, and a gallery of screenshots on the "What's New" page. Every image has a description page with source attribution and upload date, and file permissions prevent non-admin users from uploading executable files.

Learning Path

flowchart LR
  A["10: FAQ"] --> B["11: Advanced Wikitext"]
  B --> C["12: Image & Media"]
  C:::current
  D["13: Transclusion"]
  E["14: Parser Functions"]
  F["15: Subpages"]

  C --> D --> E --> F

  classDef current fill#38bdf8,color#0f172a,stroke-width:2px

Step 1: Enable File Uploads

By default, MediaWiki disables file uploads for security. You must enable them.

Edit LocalSettings.php and add or uncomment:

$wgEnableUploads = true;
$wgUploadPath = "$wgScriptPath/uploads";
$wgUploadDirectory = "$IP/images";

Then create the images/ directory and make it writable:

mkdir -p /opt/lampp/htdocs/mediawiki/images
chmod 755 /opt/lampp/htdocs/mediawiki/images
chmod 755 /opt/lampp/htdocs/mediawiki/images/thumb

The images/ directory stores all uploaded files and generated thumbnails. If permissions are wrong, uploads will fail silently.

Step 2: Configure File Types

Control which file types users can upload. Add to LocalSettings.php:

$wgFileExtensions = [ 'png', 'gif', 'jpg', 'jpeg', 'svg', 'pdf', 'webp' ];
$wgUploadSizeWarning = 5 * 1024 * 1024;  // 5 MB warning
$wgMaxUploadSize = 20 * 1024 * 1024;     // 20 MB maximum
$wgCheckFileExtensions = true;
$wgStrictFileExtensions = true;
$wgTrustedMediaFormats = [ 'image/png', 'image/gif', 'image/jpeg',
                           'image/svg+xml', 'application/pdf' ];

Security considerations:

  • Never add executable types (exe, zip, js, php, html) to $wgFileExtensions
  • $wgStrictFileExtensions rejects files with extensions not in the list
  • $wgCheckFileExtensions performs MIME type verification
  • SVG files can contain JavaScript — MediaWiki sanitizes them, but be cautious with untrusted users

Step 3: Upload an Image

Navigate to Special:Upload or click "Upload file" in the sidebar.

The upload form asks for:

  • Source filename: The file on your computer
  • Destination filename: The name it will have on the wiki (defaults to the source name)
  • Description: A summary of what the file is
  • License: Optional licensing information

After uploading, you are taken to the file's page in the File: namespace. The file page shows:

  • A preview of the image
  • File information (size, dimensions, MIME type)
  • Upload history (who uploaded it, when)
  • File usage (which pages link to this file)
  • Metadata from the file (EXIF data for photos)

Step 4: Display Images on Pages

Basic Image

[[File:Logo.png]]

This displays the full-size image inline. For large images, this will break your page layout.

Thumbnail

[[File:Screenshot.png|thumb|alt=Screenshot of settings page|Configuration settings panel]]

The thumb keyword creates a thumbnail:

  • Default width: 220px (configurable)
  • Displays a border and caption below the image
  • Generates a smaller version linked to the full-size image
  • The alt text is used by screen readers
  • The last plain-text parameter is the caption

Framed Image

[[File:Diagram.png|frame|alt=Network architecture diagram|Network Architecture]]

The frame keyword displays the image at its original size inside a frame with a caption. Unlike thumb, it does not resize the image.

Custom Size

[[File:Banner.png|800px|alt=Banner image|center]]
[[File:Icon.png|50px|alt=Small icon]]

Specify exact pixel width. The height scales proportionally. You can also specify both dimensions: [[File:Image.png|200x150px]].

Image Alignment

[[File:Logo.png|right|alt=Logo]]
[[File:Screenshot.png|left|thumb|alt=Screenshot]]
[[File:Centered.png|center|frame|alt=Centered image]]
[[File:Float.png|none|alt=No float]]

Alignment options: right, left, center, none. Images without alignment are inline, meaning text wraps around them.

Horizontal Alignment with Text

[[File:Icon-check.png|middle|alt=Check]]
[[File:Icon-download.png|baseline|alt=Download]]
[[File:Icon-arrow.png|sub|alt=Arrow]]

Vertical alignment options for inline images: baseline, sub, super, top, text-top, middle, bottom, text-bottom.

Linking from an Image

By default, an image links to its file description page. Override the link target:

[[File:Logo.png|link=Main Page|alt=Logo]]
[[File:Banner.png|link=https://dodatech.com|alt=Visit DodaTech]]

Set link= to an empty string to remove the link entirely:

[[File:Decorative.png|link=|alt=Decorative element]]

A gallery displays multiple images in a grid layout. Use the <gallery> tag:

<gallery>
Screenshot1.png|Installation step 1
Screenshot2.png|Installation step 2
Screenshot3.png|Installation step 3
Diagram.png|Architecture overview
</gallery>

<gallery widths=300px heights=200px perrow=4 caption="Installation Screenshots" mode=slideshow>
File:Screenshot1.png|Step 1: Download
File:Screenshot2.png|Step 2: Configure
File:Screenshot3.png|Step 3: Install
</gallery>

Options include:

  • widths: Image width in pixels (default 200)
  • heights: Image height in pixels (default 200)
  • perrow: Number of images per row (default 0, auto-fit)
  • caption: Gallery caption
  • mode: traditional (default), nolines, packed, packed-overlay, packed-hover, slideshow
  • showfilename: Set to true to show filenames

The packed mode creates a masonry-style layout with images of varying widths but consistent height. The slideshow mode creates an interactive slideshow.

Step 6: Advanced Image Settings

Animated GIFs

MediaWiki supports animated GIF uploads. The thumbnail displays the first frame, but clicking through shows the full animation. To control the thumbnail frame:

[[File:Animation.gif|thumb|alt=Animated diagram]]

SVG Images

SVG files render as PNG thumbnails by default. To serve the raw SVG (which allows text search and scaling):

Add to LocalSettings.php:

$wgSVGConverter = 'ImageMagick';

Or to serve SVGs directly:

$wgResponsiveImages = true;
$wgSVGMetadataCutoff = 262144;  // Read metadata from SVGs

PDF Files

PDFs are treated as multi-page images. Display a specific page:

[[File:Document.pdf|page=3|thumb|alt=Page 3 of the document]]

Without page=, the first page is shown.

Audio and Video

With the appropriate extensions (EmbedVideo, OggHandler):

[[File:Screencast.ogv|thumb|alt=Screencast|Installation walkthrough]]

MediaWiki supports Ogg Theora (video) and Ogg Vorbis (audio) natively. For other formats, use the EmbedVideo extension.

Step 7: File Management

Replacing a File

Upload a new version of an existing file. The file page shows all versions in a history table, similar to page revisions. Each version stores:

  • Timestamp
  • Uploader
  • Dimensions
  • File size
  • Comment

Deleting a File

Go to the file page and click "Delete" (requires sysop permission). Deletion removes all versions. To delete only one version, use the file history's "Delete" links.

File Redirection

Create a redirect from one filename to another:

#REDIRECT [[File:Correct-name.png]]

Useful when a file was uploaded with a typo and you want both names to work.

Category Organization

Add categories to file description pages:

[[Category:Icons]]
[[Category:Screenshots]]
[[Category:Diagrams]]

This organizes files in the Category namespace, making them findable by type.

What You Learned

  • Enable uploads with $wgEnableUploads = true in LocalSettings.php
  • Upload files via Special:Upload
  • Display images with [[File:...]] syntax
  • Use thumb, frame, and size parameters for precise display
  • Create galleries with <gallery> tags
  • Configure file types, sizes, and permissions
  • Manage file versions and organization

In the next lesson, you'll learn about transclusion — including content from one page into another.

Common Mistakes

Mistake Why It Happens How to Fix
"The file is corrupt" error Wrong MIME type or file extension mismatch Ensure the file extension matches the actual file type. A .png file that is actually a JPEG will be rejected. Re-save the file with the correct extension.
Image shows as a blue link instead of displaying Missing File: prefix or using incorrect syntax Use [[File:Image.png]] not [[Image.png]]. The File: prefix is required. The old Image: prefix still works but is deprecated.
Thumbnail displays broken icon Thumbnail generation failed Check the images/thumb/ directory permissions. ImageMagick or GD must be installed. Run php maintenance/rebuildImages.php to regenerate missing thumbnails.
Upload returns "Not a valid image" File type not in allowed extensions Add the extension to $wgFileExtensions in LocalSettings.php or use a supported format (jpg, png, gif, svg).
Gallery displays vertically instead of as a grid Missing newlines between entries Each file in a gallery must be on its own line. Entries separated by spaces on the same line break the gallery layout.
SVG images show as blank thumbnails Missing SVG converter Install ImageMagick or rsvg and set $wgSVGConverter = 'ImageMagick' in LocalSettings.php.
Users cannot upload files Permission not granted Ensure $wgEnableUploads = true and the user group has the upload permission. Check $wgGroupPermissions['user']['upload'] = true.

Practice Questions

  1. What steps are required to enable file uploads on a new MediaWiki installation?
  2. How would you display a 400px-wide thumbnail with right alignment and a caption reading "Dashboard Overview" inside a frame?
  3. What is the difference between thumb, frame, and a plain [[File:...]] display?
  4. Challenge: Create a photo gallery page for a "DodaTech Office Tour" wiki page. Upload 6 images (or use placeholder files), display them in a packed gallery with 300px widths and "Image 1" through "Image 6" as captions. Below the gallery, add individual thumbnails of the first three images with left, center, and right alignment respectively. Add a category "Office Photos" to all files.

FAQ

What file formats are recommended for wiki images?

PNG for screenshots and diagrams (lossless, sharp text), JPEG for photographs (smaller file size), SVG for logos and icons (scalable, searchable text), WebP for modern browsers (better compression than JPEG). Avoid BMP (large files) and TIFF (not supported by all browsers).

How do I prevent users from uploading malicious files?

Restrict allowed file extensions with $wgFileExtensions. Never add executable extensions. Set $wgStrictFileExtensions to true. Enable MIME checking with $wgVerifyMimeType. For additional security, install the Extension:FileUploadSecurity or use antivirus scanning at the server level.

What is the maximum file size I can upload?

PHP limits apply first: check upload_max_filesize and post_max_size in php.ini. MediaWiki adds its own limit with $wgMaxUploadSize (default 100 MB). The practical limit on shared hosting is usually 2-50 MB. For larger files, use a remote storage solution.

Can I use images from external URLs without uploading them?

By default, no. MediaWiki requires images to be uploaded for security and performance reasons. However, you can enable external images with $wgAllowExternalImages = true. Use this carefully — it allows hotlinking and bypasses your wiki's access controls.

How do I add alt text for accessibility?

Add the alt parameter: [[File:Image.png|alt=Description of image|thumb]]. Alt text is used by screen readers and is also displayed when the image fails to load. Always provide meaningful alt text for accessibility and SEO.

Mini Project

Goal: Build a complete media-rich wiki page for a software product.

  1. Create a wiki page called "DodaBrowser — Product Overview"
  2. Upload a product logo (create a simple 200x100 PNG or SVG placeholder)
  3. Display the logo at the top with right alignment
  4. Add three screenshots as a gallery with mode=packed and caption="Key Screenshots"
  5. Beneath the gallery, add three thumbnails of feature icons with left alignment
  6. Add a PDF file of a "Quick Start Guide" displayed as a framed thumbnail
  7. Add categories to all uploaded files
  8. Verify all images display correctly and the gallery renders properly

What's Next

Images make your wiki visual, but the real power of MediaWiki is reusing content across pages without duplication.

Continue to Lesson 13: Transclusion — learn how transclusion allows you to include content from one page into another, keeping your wiki DRY and maintainable.

← Previous MediaWiki Advanced Wikitext — Tables, Lists, Collapsible Sections, and Magic Words Next → MediaWiki Transclusion — Templates, Parameters, Includeonly, and Noinclude

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Mediawiki