It's better when it's simple

User Tools

Site Tools


PreserveFilenames Plugin

Compatible with DokuWiki

Lemming, Anteater, Rincewind, Angua, Adora Belle

plugin Preserves the original name of the uploaded media file (letter cases, symbols, etc.)

Last updated on
Action, Render
Conflicts with

This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.

Tagged with file, media

Download and Installation

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually. If you are manually installing, you need to rename the extracted directory to “preservefilenames”.



By default, DokuWiki normalizes media file names by means of normalized method documented in pagenames.

For example, a media file whose name is “[DW] My DokuWiki” is normalized into “” and this normalized name is used as a file name to store file entity in a file system on the DokuWiki server. However, in some cases you might want to use upper case letters, symbols or white spaces in a file name.

By installing this plugin, you can use uploaded media file with its original name instead of normalized name. Letter cases, spaces, symbols and multibyte characters in a file name will all be preserved.


File name preservation

This plugin uses a meta file to store and retrieve an original name of an uploaded file.

Storing Process:

  • Occurs when:
    • Uploading files via upload interface of DokuWiki
  • Process details:
    1. An user uploads a file (ex. "[DW] My DokuWiki") via upload interface of DokuWiki
    2. DokuWiki normalizes the file name into ""
    3. DokuWiki stores the file in "data/media/"
    4. The plugin creates a meta file "data/media-meta/"1)
    5. The plugin stores original file name in the meta file

Retrieving Process:

  • Occurs when:
    • Filling label text of media links with no designated label text in wiki pages
    • Displaying a file list in media manager
    • Inserting selected media file syntax into wiki text using javascript in media manager
    • Downloading a media file to set its file name
  • Process details:
    1. The plugin checks if there is a meta file for a media file
    2. If the meta file exists, the plugin replaces a normalized file name with its original file name

As the default behavior of DokuWiki, media links written in syntax like {{:[DW] My DokuWiki}} are recognized as normalized media IDs like {{}} by DokuWiki. And, this plugin stores uploaded media files using default file storing method of DokuWiki (e.g. stored as normalized file name).

So if you don't like this plugin, you can safely uninstall this plugin without any side effects.

Better file name handling on downloading

This plugin resolves PHP Bug #37738 and introduces RFC 2231 style Content-Disposition header for compliant browsers to mainly make a correct handling for East Asian characters in file names.

When you have a media file whose name is “日本語.zip” on your DokuWiki site and you are trying to download that file, you can download the file with the correct file name in almost all modern browsers, without seeing an url-encoded “” or any garbled file names.

For example, you can download snippet below as “文書_1.txt” instead of “_1.txt” or any garbled file names by installing this plugin.

Sample text


There are no configuration options for this plugin.


  • The refcheck feature probably does not work on a media file whose name contains special characters for DokuWiki (white spaces, parentheses, etc.).
  • When you want to preserve file names, you cannot use FTP or any other “direct” methods to upload files. Since this plugin uses meta data to store original file name, you are required to use normal file upload interface (including multi uploader) of DokuWiki to set meta data.
  • Even if original file names are different, you need to pay attention whether the names are normalized into the same media ID or not. For example, both [1].txt and (1).txt are normalized into the same 1_.txt by DokuWiki. You cannot upload both files in same namespace.


Any feedback is welcome. Please use the Issue Tracker to send your feedback.

For DokuWiki Rincewind or earlier, the plugin uses data/meta/ instead of data/media-meta/ for storing meta files.
plugin/preservefilenames.txt · Last modified: 2023-10-30 23:46 by Klap-in

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki