Table of Contents

Image and Media Handling

You can upload and embed other files into DokuWiki pages with the Image Syntax. While images, audio and video media are displayed right on the page, other files (such as PDF documents) are just linked to from the document. Please see mime for detailed information.


The Media Manager popup

Uploading new files is done with the media manager popup called from the toolbar of the Edit window.

Just use the upload form at the top right to upload a file. Optionally you can give a new name for the file. Be sure to keep the file extension correct! If you use new namespaces in the name these will be created automatically.

The fullscreen media manager lets you also upload images. Besides it can show media revisions and edit the image metadata as well.

Please note: If the administrator enabled ACL support, upload may be restricted to certain users. Users without the proper permission will not see the upload form.


Use {{}} to embed your media


An image is displayed and other media text2html.rc shows only a link with matching icon.

You may use | to add a title to your image

{{wiki:dokuwiki-128.png|The logo of DokuWiki}}

The logo of DokuWiki Try hovering over the image for showing the title as a tooltip.

How images are embedded can be influenced by various parameters. Parameters are added in URL style by appending a question mark (?) and separating multiple parameters by an ampersand (&).


By using left or right whitespaces you can choose left, right or center alignment.

{{ wiki:dokuwiki-128.png}}
{{wiki:dokuwiki-128.png }}
{{ wiki:dokuwiki-128.png }}


DokuWiki can rescale images with two methods. By default it uses PHP's libGD support if installed. Better results can be achieved with the imagemagick command line tool.

When using libGD, resizing can fail when not enough memory is available or the image format is not supported by the installed libGD version.

For resizing external images, they need to be cached at your server. To do that, you have to allow DokuWiki to download external files by increasing the size restriction in the fetchsize option.

To scale an image proportionally, give the wanted width in pixels:


This image is scaled down to a width of 20 pixels.

Or to scale an image proportionally in height, give the wanted height in Pixels, preceeded by a width of 0:


This image is scaled down to a height of 20 pixels.

When you give the width and height, the image will be scaled to exactly that height, ignoring the aspect ratio:


This image is scaled to a width of 20 pixels and a height of 50 pixels.

In DokuWiki 2009-02-14 or later, giving both width and height will crop the image before scaling to avoid distorting the image.


DokuWiki allows you to put images in a page and have them link to a page providing details about the image or to a page that contains the full image. It also allows you to include images that do not link to any other page.

By default, clicking on an image brings up a “detail” page. The detail page is rendered by the detail.php template file. The standard detail.php file shows a larger version of the image along with a listing of EXIF and IPTC metadata contained within the image (such as caption, author, date taken, etc.), along with other descriptive information.

The following syntax embeds an image in the page at full size, and clicking on this image produces a detail page providing metadata for the image:


Try clicking on this scaled-down image to see its detail page.

You may click on the image shown on the details page to get yet another page that contains only the image, shown at its actual size. Often you'll embed the image on a page at a small size and show the image on a detail page at a medium size, so that only this final direct link provides the image at its full size.

You may instead embed an image on a page such that clicking on it brings you directly to the full image in its own page. This is called a “direct” link, and it's indicated by appending the direct option to the image:


Try clicking on this scaled-down image to see its direct page.

It is also possible to embed an image in the page without having the image link to any other page. You accomplish this with the nolink option, as follows:


Try clicking on this image. Couldn't do it, huh?

You can also combine the 'nolink' and resize parameters by inserting an ampersand '&' between:


If you just want to provide a link to the image without displaying it inline, use the linkonly option:


dokuwiki-128.png This is just a link to the image.

Linking from non-DokuWiki syntax

This would be useful for example when you are using the <HTML> tags to enhance visual aspects in your page, wanting to have a <DIV> background image from the DokuWiki media storage.

Basically you just copy the code generated by DokuWiki, but you can't use resizing. The generated URL generally has three parameters; media, w and tok, and resizing with w (defining the desired width of the image) does not work unless tok parameter is also given. In other words, you can only give media URL parameter.

While you could copy the tok from generated code and use the URL in your HTML, it would break as soon as the image in question is replaced with updated content, for example.


DIV.personal_info {
  background-image:  url('{/install_dir}/lib/exe/fetch.php?media=name:space:mypic.png');

Dynamic Images

Sometimes you may want to embed a dynamic image like this one

Using the usual method:


doesn't work:


This is because DokuWiki assumes an image ends with .gif,.jpg or .png but this file ends with .php. The trick is to append an additional CGI parameter like this: &.png – the CGI will ignore this unknown parameter but DokuWiki will think it's an image.

You also need to add a question mark at the very end or DokuWiki will think the CGI parameters are caching options.

For use of { or } in the image url these need to be URL-encoded as %7B and %7C (it clashes with the media link syntax otherwise)

Example of usage of the &.png? syntax:


BTW: You can find buttonmaker webfrontends at

Removing Media

It is sometimes necessary to remove a media file, which was being uploaded before. To do this the ACL feature needs to be enabled and the user who wants to delete files needs to have the DELETE permission. Files can be deleted with the garbage can icon then.

See also: deleting media files

To link images to other resources, simply pipe that link into the image, as you would with any other text.


Example:  [[|{{wiki:dokuwiki-128.png}}]]

If the image link is to local media (like a .pdf), you can use the following syntax:


 Example:   [[this>_media/wiki:dokuwiki-128.png|{{wiki:dokuwiki-128.png}}]]


To improve the performance for the user, DokuWiki tries to cache external images. If you want to use an external image without caching you can add the nocache parameter like this.


You can combine this parameter with resizing, too.


Hitting an external Server on every pageload isn't very polite. Instead you can use the parameter recache to let DokuWiki recache the image using the interval specified in the cachetime config option: