Table of Contents
DokuWiki Template Development
You can customize the design of DokuWiki by creating a new template. A template is determined by mainly some PHP and CSS files stored in a directory beyond the
The easiest way to create a new template is by taking an already existing one as starting point. It's a good idea to use the starter template because it is clean and follows the DokuWiki template standards.
- Install the starter template (optionally, its “minimal” branch is a cleaner starting point)
- Rename the
- Select the new template in the configuration manager
Template naming conventions
A valid template name (directory):
- Should only contain the characters a-z and 0-9.
_are not allowed as:
- DokuWiki's infrastructure doesn't support them anywhere
- Using underscore will also give a popularity rating of zero.
template.info.txtand the folder name, including the page name used in the template listing e.g.
- If the same name is used by two different templates
- they are mutually exclusive and inherent incompatible,
- furthermore only one of them can have a template homepage on dokuwiki.org
It is important to have a unique base field value (i.e. template name) in template.info.txt or an already existing template with that name could be overwritten.
Templates should follow the following directory structure (all paths are relative to the template directory).
CSS files are specified in the
style.ini file. Use as many files as you like, but you should at least provide one CSS file for the screen presentation and one for printing.
<filename>.css– template's stylesheets (if more than a few are provided, it makes sense to group them in a
main.php– general layout of DokuWiki
detail.php– the image detail page
mediamanager.php– the media-selection popup
images/– all images used in the template (if any)
conf/– configuration files (optional, if configuration is used)
metadata.php– configuration metadata describe properties of the settings as used by the Configuration Manager
lang/– language files
<lang code>/lang.php– localization strings used in the template (optional, use when needed)
<lang code>/settings.php– localization strings used in the configuration manager (if configuration is used)
style.ini– see style.ini
favicon.ico– favicon (can be overwritten by uploading another one into the root or wiki namespace when tpl_favicon() is used)
template.info.txt– A text file with template information required!
Handling of configuration settings is analogous to plugins. Use
tpl_getConf(<setting>) to retrieve custom template settings. Saved local settings are stored in DokuWiki's global
Inner workings explained
A list of available functions can be found in API documentation. Some specialities are listed here.
This function outputs the page body, or in other words the content of your wiki page, including the TOC. You can prevent it from outputting the TOC by passing
falsewhile calling it:
This can be used to separate the TOC from the content and place it somewhere else on the screen. See
tpl_toc()below for further details.
By default, the
tpl_content()function will take care of displaying a Table of Contents itself, prepending it to the actual page content. If your template uses a sidebar or other more complex layout you may want to place the TOC independently from the page content. This can be done with the
tpl_toc()function. When using it, it is important to disable automatic TOC placement by passing the argument
<div id="content"> <?php tpl_content(false)?> </div> <div id="sidebar"> <?php tpl_toc()?> </div>
tpl_toc()function renders the TOC from three different sources: a global $TOC variable, the page metadata or the
getTOC()method of admin plugins. Because there is no metadata available for old revisions or preview
tpl_toc()can only use the global $TOC variable for these cases. Because the $TOC variable is filled by the page renderer this will only work when
tpl_toc()is called after
tpl_content(). If this is not possible in your template layout you may use output buffering to circumvent the problem.
<?php // render the content into buffer for later use ob_start(); tpl_content(false); $buffer = ob_get_clean(); ?> <div id="sidebar"> <?php tpl_toc()?> </div> <div id="content"> <?php echo $buffer?> </div>
- Further many other useful template functions are available. Please have a look in API documentation.
Global Variables And Constants
For a complete list of useful global variables and constants please refer to the environment page.
Almost at the bottom of the default template's main.php file you'll see a function call to
tpl_indexerWebBug(). The function generates a HTML
<img> tag which results in a request to
lib/exe/taskrunner.php. This vital part of DokuWiki provides important housekeeping work to keep the wiki running smoothly. All templates should include this function, without it the wiki may not function correctly (for example the search index wont be built).
A class named
dokuwiki should be added to some content surrounding element (either around everything or at least around
tpl_content()) in each template's main.php, detail.php and mediamanager.php. This is to make sure that DokuWiki's styles don't interfere with other styles if it gets integrated into an existing site with potentially conflicting CSS.
Include Hooks are a simple way to add some static content to your DokuWiki installation without writing your own Template. You can use them for adding a standard header at the top or a disclaimer at the bottom of each page.
The DokuWiki's default template looks for files with special names in the template directory and simply includes them at the correct places when displaying the page. You can add whatever HTML or even PHP you like into these files. Of course this only works if you are using the dokuwiki template or a template supporting the same include hooks (like the starter template).
Converting existing templates
If you're lacking design skills you can also convert existing templates. There are lots of free options available. If you'd like to publish one of those as well, please make sure it is GPL2-compatible.
Here are a few problems template developers run into and how to avoid them:
Some template developers experience problems with DokuWiki cacheing CSS and JS files due to this option being on, although this has been hard to pinpoint. To be safe, turn this off temporarily.
Use "forced refreshing" after you make changes to CSS files
You can accomplish this by pressing Ctrl+F5 or by holding down shift-control-alt and hitting the refresh button in your browser.
This is not due to how DokuWiki works, but how current browsers cache files. Browsers cache stylesheets even when new versions are available, so you will need to do this.
Publishing a Template on dokuwiki.org
If you created a template, please share it with the community. Just create a page named after your template in the template namespace. E.g. if your template folder is named
sample create a page
template:sample here in the wiki.
The page should contain all needed documentation on how to install and use the template. Adding screenshots might be a good idea as well.
At the top of the template page a few metadata fields have to be filled in. A description of each field can be found on the Repository Plugin page.
From version Ponder Stibbons on an automated update signalling is possible. For the update process to work properly it is necessary that the date “Last updated on” on the template's wiki page equals the date in the file template.info.txt in the source tarball/zip file. If this is not the case the update will not take place or the “Update” signal persists.
Uploads are not allowed on dokuwiki.org, so you need to host your template files somewhere else. We recommend to manage your source with a Revision Control System like git. If you do, it's easiest to use a public repository host like GitHub which also offers a bug tracker for your repository.