Plugin : filelist

---- plugin ----
description: Provides a syntax for adding linked and sorted lists of files as selected by wildcard based glob patterns to a wiki page
author     : Dokufreaks (previous author: Gina Häußge)
email      : freaks@dokuwiki.org
type       : syntax
lastupdate : 2016-09-10
compatible : Binky, Ponder Stibbons, "Hrun",detritus,"Elenor of Tsort", "Frusterick Manners", "Greebo"
depends    : 
conflicts  : 
similar    : medialist
tags       : file, listing, download, media, filter, odt

downloadurl: https://github.com/dokufreaks/plugin-filelist/archive/master.zip
bugtracker : https://github.com/dokufreaks/plugin-filelist/issues
sourcerepo : https://github.com/dokufreaks/plugin-filelist/
screenshot_img : https://github.com/dokufreaks/plugin-filelist/raw/master/FilelistScreenshot.png


The filelist plugin provides a syntax for adding linked and sorted lists of files as selected by wildcard based glob patterns to a wiki page and thus allows dynamically including file listings of arbitrary filesystem locations and media namespaces. Using the additionalfilename command, one can also add a single link to a file out of a list anywhere in the text, which can be used to automatically keep download links for software releases up to date with the most recent upload.


The filelist plugin has three configurable options:

Option Description
allow_in_comments Whether to allow the usage of the filelist/filename syntax in comments by the discussion plugin. Defaults to 0 and thus prohibition of the plugin usage in this scenario.
allowed_absolute_paths A comma-separated whitelist of all paths beneath which to allow the scanning using the filelist/filename syntax. Defaults to the Dokuwiki basedir DOKU_INC.
web_paths A comma-separated list of URLs via which the previously defined absolut paths are reachable to wiki users. This list MUST contain exactly the same amount of entries as allowed_absolute_paths. Defaults to the Dokuwiki base-URL DOKU_URL as a mapping for DOKU_INC.

The filelist plugin provides two new commands to be used in wiki pages, filelist and filename. The general command syntax for both is the following:

{{[ command ]>[ pattern ][ parameterlist ]}}
  • command must be either filelist or filename.
  • pattern is a searching pattern for files to include in the generated list, defined using the pattern syntax of the unix fnmatch function. An example: If you want to include all files ending on .txt in the folder some/path/ 1) ) , you would usesome/path/*.txt as the pattern (and the parameter direct=1, see parameters below). Analogue to this, to include all jpeg media files in :some:namespace, you'd use :some:namespace:*.jpg.
  • parameterlist can be used to define optional, & separated parameters (defined as key-value-pairs). For a list of supported parameters, see below.

The filelist plugin supports both absolute as well as relative paths into the filesystem or Dokuwiki media namespaces. All paths are checked against a whitelist of allowed paths for scanning (as defined via the configuration setting ''allowed_absolute_paths''). Paths which are not located below these whitelisted paths are not allowed for globbing and thus filelist/filename calls to such paths fail. Per default, the Dokuwiki basedir as defined in DOKU_INC is included in this whitelist and mapped to the Dokuwiki base-URL, DOKU_URL.

Relative paths into the filesystem are interpreted relative to the Dokuwiki basedir. Relative media paths (without a leading : that is) are interpreted relative to the namespace of the currently active page. Thus, :snippets:dokuwiki:* and * would be interpreted the same on the current page :snippets:dokuwiki:filelist.

Name Description Possible values Default
direct Whether to interpret the given pattern as a direct path in the file system or as an dokuwiki media id. Defaults to media id. 0 or 1 0
sort The property by which to sort the internal file list. By default, the file name is used, with upper case being sorted before lower case (use iname for a case insensitive sorting criteria). name,iname,ctime,mtime,size name
order Whether to sort the internal file list ascending or descending. Sorting in ascending order is the default. asc,desc asc
cache Whether to disable or enable caching for the page. Default is no caching. 0 or 1 0
filelist specific parameters
offset The offset in the internal file list from which on to display the list. Default is an offset of 0. any numeric value 0
limit The number of files to display, beginning at index offset. A number of 0 means to display all available files. any numeric value 0
style The style to use for display. list creates an unordered bullet list (the default), olist an ordered list, table a table view and page a heading/section based view of the selected files. list,olist,table,page list
tableheader Whether to show the table header describing the table columns. Off by default. 0 or 1 0
tableshowdate Deprecated, see showdate. Off by default. 0 or 1 0
tableshowsize Deprecated, see showsize. Off by default. 0 or 1 0
showdate Whether to show the file modification date in the table view. Works with all style options. Off by default. 0 or 1 0
showsize Whether to show the file size in the table view. Works with all style options. Off by default. 0 or 1 0
recursive Whether to do a recursive file crawl starting at the defined basepath. If this parameter is set to 1, the wildcard part of the search pattern is applied to each found subdirectory. If no files are found, the subdirectory is not included in the search result. All display styles besides table will show the result in a hierarchical structure; table will first flatten the result by prepending all found files with there subtree pathname (note that this happens before sorting). 0 or 1 0
titlefile The filename of a file which to lookup in each subtree if recursive is set to 1 and whose content to use as title for the directory. It will be ignored in the results of the filelisting itself. Defaults to _title.txt. Example: A _title.txt file containing “My special title” found during a crawl on the subpath my/subpath will be rendered as having the name “My special title” instead of “subpath”. any filename _title.txt
preview Whether to show a preview image for image files. Off by default. 0 = off,
1 = image and file icons,
2 = image only,
3 = file icon only
previewsize Size in pixel for preview images. Is only meaningful if preview is not 0. Default is 32. Any value greater 0 32
onhover Whether to show a larger preview image (300×300 px) if the mouse pointer is hovered over it. Uses JavaScript. Is only meaningful if preview is not 0. Default is off. 0 or 1 0
randlinks Whether to generate random links with timestamps to prevent linked-to files from being cached. Off by default. 0 or 1 0
link Whether to generate links for the filelist. On (2) by default. 0 = no links just plain text,
1 = simple text link,
2 = link with small file icon
listsep List separator to use between the fields (e.g. “linktext, showsize”). Default is , . Any character sequence ,
ftp Whether to generate FTP links instead of HTTP links. Off by default. 0 or 1 0
filename specific parameters
index Which specific item to select for display from the internal file list. The default is the first one. any numeric value 0


Example 1
Example 2
Example 3


The links to the details description and syntax seem to be not working, so we're not able to work out how this plugin works — Simon, 29 May 2015

Works with my DokuWiki version 2010-11-07. A problem was discovered, which is the filelist does not display the files for unregistered user. The ACL is correctly set for ALL and using normal syntax the file is displayed and accessible. — Münchener, 14 Feb 2011

I played around with getting this to work for a while, before realising that, under Windows, the case of the drive letter does actually matter! So, both savedir and this plugin's allowed_absolute_paths I had to change from d:/www-data/wiki/ to D:/www-data/wiki/samwilson 2011-10-05 05:46

I had no end of trouble getting this to work on Bitnami WAMPStack Server (Windows, Apache, MySQL, PHP). I finally discovered that not only is the case of the path important, the mix of \ and / path separators used in the dokuwiki config path is important. It works now that I used the exact path specified in the dokuwiki “savedir” config, eg C:\Program Files\Bitnami WAMPStack\apps/dokuwiki/data/ (and no quotes). Obvious once stated. — alan 2012-12-04 11:58

In my judgement this plugin does not work with Rincewind. At least not in my configuration. In Rincewind I could this only get working with the direct-option and absolute paths, not the namespace notation. The namespace-notation resulted in Access-denied. And 'working' means only display, clicking on a file-link in the list resulted in a server-error :-(

The medialist-plugin is a working alternative (if using a patch somebody provided in the dokuwiki-documentation).

Examples: So this displayed a list


This did NOT:


Omission of &direct won't work either.

There seems to be no real alternative to this plugin, it would be nice if this could be repaired (or my mistake in the usage of it be clarified) The bug-report link on the owner's list points to nirvana :-(

It works with Rincewind and Angua.

I had to go to Admin > Configuration Settings > Filelist Plugin Settings and give values like the following:


More information from Wikipedia.

I also had to consider this. Firefox blocks links to local files for security purposes. So I added the LocalLink extension to Firefox, as described in that page.

With this modifications, I can use something like this:


or like this:


to list the contents of my file system.

In Firefox with the LocalLink extension, one may right-click on a link/element from that list and select Open Link In Local Context.

I have tested this in Mac OS X and Ubuntu. I have made a trial in Windows 7 with the following values (also trying lower case c:) but I could not make it work and I got [n/a: Access denied].




works without any modification as expected in Rincewind

After upgrading to Binky, previously working code now displays:

[n/a: Access denied]

I am logged in as admin and have made no changes to ACL rules.

The configuration settings have not changed, path on server & url are correct:

My previously working entries were of different format to discussion above (as follows):


Has anyone got this very useful plugin working on Binky?

charles.minto 2014/01/24 00:44

All these:




work as expected on Binky.

JohnG 2014-02-12

Thanks. I finally figured out the problem, my mistake. I had to change my entry in the configuration settings from DOKU_INC to:


as the weburl.com.au points to the subfolder.

charles.minto 2014/03/19 11:55

Actually after tracing through the file list code using basically print statements, I found out what wasn't working for me. I thought I should post that by default out of the box if you haven't changed paths much, then you want the allowed_absolute_paths to point to your sites dokuwiki/data/media directory and you want your URL to be to your site. So for us we have something like


Then in the actual code, to for example list all files in the media director of the form Notes*.pdf for the name space project, we use something like:


jasonharris 2014/04/27

It still doesn't work for me in Hrun. I set


but I get Access denied when I use the filelist plugin on my pages

— Hana Skoumalová 2014/12/18

The default setting DOKU_INC for the absolute path did not seem to work. It just got me the dreaded access denied message. However, I was able to get the plugin working by:

  • set the absolute path to /usr/local/doku/data on a server administrated by me.
  • set the absolute path to / on a shared space hosted by an ISP. In this case I also set the DOKU_URL to the URL this wiki can be reached.

KaiMartin 2015-02-09 03:16

on my dokuwiki hrun on a synology NAS and using multiple animals, i only got it working with:

  • plugin»filelist»allowed_absolute_paths = /var/services/web/wiki/dokumente/data/media/
  • plugin»filelist»defaults = /wiki/dokumente/_media/


  • /var/services/web is the path given by _SERVER[“HOME”] using phpinfo
  • /wiki/dokumente is the path for the animal. in generell i think it will be just /dokuwiki

by using the direct parameter and absolute path like this: {{filelist>/var/services/web/wiki/dokumente/data/media/*&direct=1&recursive=1}}

The setting DOKU_INC works as expected in Detritus. If you still get access denied messages, the cause may be an inappropriate setting of the direct= parameter. — KaiMartin 2015-10-12 23:24

Great plug-in but seems old and a bit unstable now and then? Our intranet depends on it because of the great real-time connection between file actions in 'windows explorer' and the file lists in the wiki (indirect via mounting of certain directories on a Windows server). Is there anything a non-coding user like me could do to keep an essential plugin like this one future-proof?
—-2016.03.31 17:05 - MartinNL

You can always pay someone to maintain this plugin. See bounties and professional support and services (although you might be more successful finding someone elsewhere). — Anika Henke 2016-04-03 19:23
Thank you, I am going to discuss this here.

—-2016.04.04 08:15 - MartinNL

I have copied the essentials from the developer's web site, since the links are broken.
Myron Turner 2015-06-09 03:39

The original page with illustrated examples is here: http://web.archive.org/web/20150411215519/http://www.foosel.org/snippets/dokuwiki/filelist. This link was provided in a post on the forum (https://forum.dokuwiki.org/thread/12665). Please make any necessary changes.

The original git repository of the plugin can be found at Github.

  • wiki/filelist.txt
  • Dernière modification: 06/06/2019/ 00:46
  • par Geco-iT Administrator