DokuWiki Media Management — Uploading, Galleries, Revisions, and Cleanup

In this tutorial, you'll learn how to upload, organize, and manage media files in DokuWiki, including images, documents, archives, and galleries with revision tracking and cleanup.

What You'll Learn

• Accessing the Media Manager
• Uploading files (images, PDFs, archives)
• Organizing media by namespace
• File deletion and replacement
• Media file revisions
• Creating image galleries
• Configuring allowed file types and size limits
• Cleaning up unused media files

Why It Matters

Media files are half of your wiki's content. Screenshots, diagrams, PDF documents, and other files make documentation useful. Without proper media management, your wiki becomes a mess of orphaned files, outdated screenshots, and confusing upload locations. Understanding how DokuWiki handles media keeps your file Repository organized and your pages looking professional.

Real-World Use

A product documentation team uploads screenshots for each software version. They use the Media Manager's namespace structure to organize files by product and version: media/product/v2/screenshot.png. When they update screenshots for a new version, they upload to a new namespace rather than overwriting old files. The team can always find the correct screenshot for each version, and the media repository stays clean.

Learning Path

flowchart LR
  A[Tables] --> B[Media Management]
  B --> C[Sidebar]
  C --> D[Namespaces]
  D --> E[Namespace Management]
  E --> F[Page Revisions]

The Media Manager

Access the Media Manager by clicking the "Media Manager" link in the page toolbar or navigating to /wiki/lib/exe/mediamanager.php.

The interface has three panes:

+--------------------------------------------------+
| Namespace tree  | File list    | Preview/Upload   |
|                 |              |                   |
| [media]         | file1.png    | [Upload form]     |
| [screenshots]   | file2.pdf    | [Preview pane]    |
| [documents]     | file3.zip    | [File info]       |
+--------------------------------------------------+

• Left pane: Browse namespaces (folders) for media
• Center pane: List files in the selected namespace with details
• Right pane: Upload new files, preview selected files, view file information

Uploading Files

Step-by-Step Upload

1. Open the Media Manager
2. Navigate to the namespace where you want the file
3. Click the "Upload" button or drag-and-drop a file
4. (Optional) Add a comment describing the file
5. Click "Upload"

The file appears in the selected namespace and is immediately available for embedding in pages.

Upload from a Page

You can also upload directly from a page editor using the image button in the toolbar. This opens the Media Manager in a popup where you can upload and select files without leaving the page editor.

Organizing Media by Namespace

Just like pages, media files are organized by namespace. The root media namespace is data/media/. Sub-namespaces become subdirectories.

data/media/
├── wiki/                  # Default namespace for wiki graphics
│   ├── logo.png
│   └── favicon.ico
├── projects/
│   ├── diagram.png
│   └── report.pdf
├── team/
│   └── photos/
│       ├── alice.jpg
│       └── bob.jpg
└── presentations/
    └── roadmap-2026.pdf

To embed a file from a specific namespace:

{{projects:diagram.png}}
{{team:photos:alice.jpg}}

Good namespace organization prevents filename collisions and keeps related files together.

File Types and Size Limits

DokuWiki restricts which file types can be uploaded for security reasons. Default allowed types include:

Configuring Allowed Types

Edit conf/local.php to change allowed MIME types:

<?php
$conf['mime'] = 'jpg,jpeg,png,gif,svg,pdf,zip,gz,tar';
$conf['mime_exclude'] = 'exe,bat,com,dll';

Setting Upload Size Limit

<?php
// conf/mime.local.conf
// Maximum file size in bytes (default: 150000 = ~150KB)
$conf['maxuploadsize'] = 5000000; // 5 MB

The actual maximum upload size is also limited by PHP's upload_max_filesize and post_max_size settings in php.ini.

File Revisions

DokuWiki tracks revisions for media files, just like pages. When you upload a new version of a file, the old version is preserved.

To view file history:

1. Open the Media Manager
2. Select a file
3. Click the "History" button (clock icon)

The history shows each upload with:

• Date and time
• Uploader username
• File size
• Comment (if provided)

Reverting to a Previous Version

1. View the file history
2. Find the version you want to restore
3. Click "Revert" or download that version, then re-upload it

Creating Image Galleries

DokuWiki does not have a built-in gallery function, but the Gallery plugin provides this capability.

Installing the Gallery Plugin

cd /var/www/html/wiki/lib/plugins/
wget https://github.com/splitbrain/dokuwiki-plugin-gallery/archive/master.zip
unzip master.zip
mv dokuwiki-plugin-gallery-master gallery

Using the Gallery Plugin

{{gallery>namespace:subnamespace?200x150&lightbox}}

Parameters:

• namespace: The media namespace containing images
• 200x150: Thumbnail size (width x height)
• lightbox: Enable lightbox view on click

Example:

{{gallery>team:photos?300x200}}

This creates a gallery of all images in data/media/team/photos/ displayed as 300x200 thumbnails.

Deleting Media Files

Individual File Deletion

1. Open the Media Manager
2. Select the file
3. Click "Delete"

DokuWiki asks for confirmation. Deleted files are removed from the filesystem, but their revision history may still exist if you have configured it.

Bulk Deletion

There is no built-in bulk deletion. To delete multiple files:

1. Use the Media Manager to delete files individually
2. Or use the command line: rm data/media/namespace/unwanted-file-*

Be careful with command-line deletion — there is no undo.

Cleaning Up Unused Media

Over time, wikis accumulate unused files — screenshots from old versions, test uploads, outdated logos. DokuWiki does not have a built-in "unused media" report, but you can find orphaned files manually:

1. List all media files: find data/media/ -type f -name "*.png"
2. Search your wiki pages for references to each file: search for the filename in page content
3. Delete files that are not referenced anywhere

The data/media/attic/ directory may also contain old file revisions that you can purge to reclaim disk space.

Common Mistakes

1. Uploading to the wrong namespace: When pages are in projects:, the media link {{diagram.png}} looks in data/media/projects/. If you uploaded to the root, the image will not display. Use {{:diagram.png}} (with leading colon) for root media.
2. Overwriting files without version comments: Always add a comment when uploading a new version. Without comments, the file history is not useful for finding specific versions.
3. Uploading oversized images: A 10 MB screenshot does not need to be 10 MB. Resize and compress images before uploading. Use tools like ImageOptim, TinyPNG, or the convert command.
4. Ignoring file naming conventions: Files named screenshot1.png, final-v2.png, and image(1).png are hard to identify. Use descriptive names like dashboard-admin-panel.png or installation-step-3-database-config.png.
5. Not checking file permissions: If the web server cannot write to data/media/, uploads will fail silently. Verify permissions when upload problems occur.

Practice Questions

1. How do you embed an image from the documents namespace on a page in the projects namespace?
2. What is the difference between {{image.png}} and {{:image.png}} when used on a page inside a namespace?
3. How do you configure DokuWiki to allow PDF uploads up to 10 MB?
4. Challenge: Set up a complete media organization system for a product documentation wiki. Create namespaces for: screenshots (by version), PDF documents, logo and brand assets, and team photos. Upload at least one file to each namespace. Create a gallery page that displays all team photos as a thumbnail grid. Create a second page that embeds screenshots from a specific version namespace. Configure upload limits to allow 10 MB files. Add at least 5 file types (png, jpg, pdf, zip, csv) to the allowed types list.

FAQ

Mini Project

Goal: Build a media library for a wiki documentation project.

1. In the Media Manager, create a namespace structure: screenshots/v1/, screenshots/v2/, documents/, branding/
2. Upload at least 3 images to screenshots/v2/
3. Upload a PDF document to documents/
4. Upload a logo to branding/
5. Create a page that embeds images from screenshots/v2/ at different sizes (200px, 400px, original)
6. Create a gallery page using the Gallery plugin showing all images from screenshots/v2/
7. Upload a new version of one image and add a descriptive comment
8. Delete a test image and verify it is removed

What's Next

With media files organized, create a sidebar and navigation to help users find their way around your wiki.