Tips and Tricks

This is the place to collect all your little Tips and Tricks for DokuWiki Usage.

Usage Tips

Link Short Description
TailorWikiRules How to adjust DokuWiki to fit your needs
Syncing with Unison Sync two wikis using unison
timezone Set the server’s Timezone
mailconfig Tips on making mail work

Extending the Syntax

Most of these tips need to be adjusted for the new Parser and will not work out of the box. They may be better implemented by using the new plugin system though. A list of plugins using the new plugin interface lives at the plugin-page.

Link Short Description
LatexRender Render LaTeX-fragments to images, can be used as an alternative to MathML
Invert Headers Inverts the syntax for Headline (i.e., ‘=’ = H1, ‘==’ = H2, etc
Tables with Rowspans Support for columns to cross rows ( rowspans ) in tables using new syntax.
Echo PHP variables securely Display predefined variables in pages
Markdown Adding Markdown to DokuWiki
SVG Support Collaborate on vector images using the SVG format
GraphViz Support Collaborate on graphs
Base links Make normal (non-wiki) Base links to your wiki hierarchy

Extending Layout and Styling

Some of these tips may be implemented better by using the new template mechanism. You are encouraged to rewrite them accordingly.

Link Short Description
CustomQuoting Change the style of Quoting
Hide php Code Hide code in <php>...</php> tags when the user doesn’t have permission to edit the page.
format_user Using CN from client certificate when displaying username
Folding Sections Allows sections of text to be folded (shown or hidden by user interaction)
Folding Sections Revisited A variation on the above tip
HierarchicalBreadcrumbs Another aproach on breadcrumbs navigation
Pretty Recent Changes the recently updated page to include day headers Fix for July 1 Revision
smiley toolbar Add a smiley toolbar
Underscores to blanks Convert Underscores back to blanks in titles
'pre' section with wrap<pre> section with wrapping

Adding new Functionality

Link Short Description
ResetPassword Reset password for a user in auth_plain
AllowUserToSetPassword Allows the user to define the password to use for login, instead of receiving it by e-mail.
Edit Form Mods Extend the Editform
BrowserLanguageDetection Change the UI language automatically
namespaceindex Show the index of a namespace when browsing to a namespace
Calendar Add a Calendar to Dokuwiki - no way to add comments! and html_head(); is undeclared!
JSCalendar Create a DokuWiki-Calendar
PDF Export PDF export using html2ps and pstopdf
View Counter Count Page Views
Print View Button make use of ?do=export_html
User Link use an extra wiki-page for users
.htaccess Authentication Use .htaccess authentication instead of the login form

Integration in other Software

Link Short Description
Integrate with phpBB How to integrate DokuWiki with phpBBs authentication
Integration with IPB 2.x How to integrate Dokuwiki with IPB 2.x authentification
Use DokuWiki Syntax in phpBBUse DokuWiki Syntax in phpBB (in German)
Integrate with Mambo CMSHow to integrate DokuWiki with Mambo CMS (Spanish)

Interacting scripts and tools

Link Short Description
Maintainance Cronjobs to keep your wiki clean
Wikemail a script to import email into DokuWiki Dumps some hardware info in DokuWiki format
OpenOffice Macro converts an OpenOffice document to DokuWiki format
Word Macro converts an MS Word document to DokuWiki format
Backup Script A small shellscript to backup your wiki data and media, including rotation.
UpgradeScript A small script to make DokuWiki updates simpler
HTMLtoWiki How to convert HTML to Dokuwiki syntax
Shorttags A script to convert short tags to long forms in Dokuwikis source code

Move to their own pages

FIXME: These tips should be moved to their own pages.


Think of NameSpaces before starting to create pages. Although it’s possible to rename pages managed by DokuWiki (which is not so easy in other WikiEngines) it’s not a simple process: requires skills in regular expression pattern matching and unix shell scripting commands.

The NameSpaces work like content categories. Create a NameSpace when you see that several pages of related content will be created, and build a top-level page that aggregates them all.

This initial “stalling” period has helped me a lot in breaking down (outlining) the documentation to be produced by wiki users. Without it, a scattered and cluttered unique namespace would not serve our documentation requirements well.

To make a new namespace simply create a wiki link with a colon separating the namespace from the page name. For example:

My 2 cents: To ease navigation, especially when using hierarchical breadcrumbs, it’s nice to have a page with the same name as your NameSpace. You may put there general description of the NameSpace and some links to the main pages in this Namespace. For example: [[mynewspace]]

HOWTO: Rename Pages

Note: This tip assumes one has either Cygwin installed when running DokuWiki under Windows or has text file utilities installed under Unix/Linux. But following this tip prevents DokuWiki from keeping a coherent page history (old revisions). Remember to back up all raw text files and data.

:?: How-To Rename a set of pages? Use sed regular expressions to match a filename pattern and replace it with a new filename pattern.

:!: Example: Rename all pages starting with <project_name> to another prefix:

for f in `ls *.txt`; do sed -e 's:\[\[project_name\(.*\)\]\]:[[prj_code.\1]]:g' $f > $; done
for f in `ls *.new | sed -e 's:\(.*\)\.new:\1:g'`; do mv $ $f; done
for f in `ls *.txt | sed -e 's:project_name\(.*\)\.txt:\1.txt:g'`; do mv project_name-$f prj_code-$f; done

Explanation: The first command uses sed to find all occurrences of a DokuWiki FreeLink that starts with project_name and replaces them with a new FreeLink that is like the old one except that instead of prefix project_name it has prefix prj_code. The second command is used to replace the old raw text files (with old FreeLink) with the new raw text files (with new FreeLink). Finally, the third command renames the files that match those FreeLinks, by replacing the prefix project_name with prefix prj_code in their filename.

Relative links

Relative links can be created using the special interwiki shortcut this. However it may make more sense to create additional shortcuts for certain services like a bugtracking software or WebCVS.

Here is an example for having a ViewCVS installation installed on http://server/cgi-bin/viewcvs.cgi. Just add the following line to conf/interwiki.conf:

cvs  http://server/cgi-bin/viewcvs.cgi/{URL}

You then can reference files in the CVS directly with [[cvs>afile/in/cvs]]

You probably want {NAME} rather than {URL} here...

Tight Code Boxes

Is there a way to tighten the boxes around code and pre-formatted boxes?

For browsers with good rendering engines, there is the CSS max-height declaration (works in Opera, Mozilla, probably Safari):

pre {max-height: 20em; overflow: auto; margin: 10px auto}
body > * pre {width: 85%;} /* given for good browsers; IE doesn't understand child selector*/

That will create a centered code box that will never grow greater than 20em, if it does a scrollbar is added. IE will fail to understand either max-height or margin: auto (for margin: auto, you need to make the parent box’s text-align: center!) - but it doesn’t matter as it doesn’t ever get the width declaration... — Ian

Find out who's contributing most

$> cat changes.log |awk '{print $2}'|sort|uniq -c|sort
Or sorted from highest to lowest (works on Cygwin, should also work on Linux and other Unix):
awk '{print $2}' changes.log | sort | uniq -c | sort -r
Very nice tip, could this “code” be integrated in DokuWiki? Making it a new page, statistics, that outputs the most active IPs (how about (ACL?) users?) and the number of pages and total size of the content? :: FIXME :: This should be moved to Wiki:Discussion, right?
I have found that the changes.log file format does not match the code above - the username is the 4th column and not the 2nd. The one-liner below works for me with version of DokuWiki dated1) 2005-02-18.
cat changes.log | cut -f4 | sort | uniq -c | sort -r

Make a Dokuwiki Index

I use the following script to make a simple Index.

cd $1
echo "|Last Update: ^ $(date) ^" > index.txt
foreach line in $(find  . -iname "*txt"|grep -v "\.cache")
        val=`echo $line| perl -pe "s/^\.\///;s/\//:/g;s/\.(txt|html)$//"`
        echo "  -[[$val|$val]]"
done >> $1/index.txt

and the following cronjob

2,22,42  * * * * /usr/bin/dokuwiki_index /path/to/dokuwiki/data/

*sample Output:*

Adding absolute links

If, like me, you keep your DokuWiki in a subdirectory of your site you might find it convenient to be able to refer to pages above the root of DokuWiki by using absolute url links in the form:


or similar.

Open inc/parser.php and find the following in the linkformat($match) function:

    // email
    $link = format_link_email($link);
    // wiki link
    $link = format_link_wiki($link);

And change it to:

    // email
    $link = format_link_email($link);
  }elseif(strpos($link['url'],'/') === 0){
  	// absolute URL (for current site)
  	$link = format_link_absoluteurl($link);
    // wiki link
    $link = format_link_wiki($link);

Now add the following function to inc/format.php:

 * format absolute URLs
 * @author Robert Meerman <>
 * @adapted from the work of Andreas Gohr <>
function format_link_absoluteurl($link){
  global $conf;
  //simple setup
  $link['class']  = 'wikilink1';
  $link['target'] = $conf['target']['wiki'];;
  $link['pre']    = '';
  $link['suf']    = '';
  $link['style']  = '';
  $link['more']   = 'onclick="return svchk()" onkeypress="return svchk()"';
  $link['url']    = $link['url']; //keep it
  $link['title']  = htmlspecialchars($link['url']);
  if(!$link['name']) $link['name'] = htmlspecialchars($link['url']);
  //thats it :-)
  return $link;

That’s it! When the first character of a link is ‘/’ it will be an absolute URL on your site, allowing you to easily mirror your wiki on different domains (i.e. localhost and

Robert Meerman 2005/03/16

Another way of doing this

Wouldn’t it be simpler to just use the interwiki feature as in the above tip. Just create an interwiki in conf/interwiki.php like this:


And then reference any Absolute Link like this:


That way you won’t have to modify any dokuwiki source code... which is much easier when it’s time to upgrade to a newer version! Isn’t it?

You can even add your own favicon instead of the generic external link one by puting a 16×16 mysite.gif or mysite.png in the interwiki dir.

While I agree this alternative method is simpler, I prefer my original method because it creates a much tighter intergration — the links are indistinguashible from inter-site wikilinks, which is what I want when I am linking to, say, a downloadable PDF file or non-wiki-generated statistics page.

Adding absolute media

Very similar to the above, but for inserting images.

Open inc/format.php and find the format_link_media($link) function. Scroll down a bit to “namespace mangling for internal images” and change it to look like so (if we find a ‘/’ as the first char of the src, we leave it alone):

  //namespace mangling for internal images
    // Check for absolute insite URL
    if(strpos($src,'/') === 0){
      // Do nothing
    } else {
	    $ns = getNS($ID);
		//if src starts with . add current namespace
		if(strpos($src,'.') === 0){
		  $src = $ns.':'.substr($src,1);
		//if src contains no namespace add current namespace if any
		if($ns !== false && strpos($src,':') === false ){
		  $src = $ns.':'.$src;

Then (still in inc/format.php) find the img_cache(&$csrc,&$src,&$w,&$h,$nocache) function and change the following:

  //check if it is external or a local mediafile


  //check if it is external/absolute or a local mediafile
  if(strpos($src,'/') === 0 || preg_match('#^([a-z0-9]+?)://#i',$src)){

That’s it! Now if you have your wiki in a subdirectory of your site you can insert pictures from above the wiki’s root by preceeding the source url with a ‘/’! Eg: {{/templates/button.gif}}

Robert Meerman 2005/03/16

Another, ?simpler?, way of doing this

This tip suppose you can logon to your web server... might work only on UNIX like servers (Apache).

Another way of doing this without changing the source code (easier espacially when upgrading the dokuwiki engine) might be to add a link in the media dir to another dir containing your images.

In the above example that would mean, doing this when you are logged onto your server:

cd dokuwiki/media
ln -s ../../templates templates

Then you only have to add this line to your document:


When upgrading dokuwiki, the media dir will be kept as is, thus you have nothing to do...


I modify auth_plain.php to auth_mail.php for authentication with pop3/imap server using PHP imap-open function.

auth_mail still use conf/users.auth, and just use PHP‘s imap_open function to check username and password.

firstly, add/modify config in config/local.php below:

    // change authtype as 'mail'
    $conf['authtype']  = 'mail';
    // new add config for imap_open's first parement
    // about which pop3/imap server you will use.
    // look for detail.
    // below are using pop3s service from localhost
    $conf['mailserver'] = ''{localhost:995/pop3/ssl/novalidate-cert}';

and auth_mail.php source code below:

 * POP3s authentication backend
 * Use POP3s service of mail server for authentication.
 * Users use login ID and password the same with pop3s.
 * Other user properties are stored in conf/users.auth
 * password field fills with a star(*) 
 * @license    GPL 2 (
 * @author     lss <>
 * Modify from auth_plain.php from Andreas Gohr <>
 * Check user+password [required auth function]
 * Checks if the given user exists and the given
 * plaintext password is authencate by imap_open
 * @author   lss <>
 * @modify from  Andreas Gohr <>
 * @return  bool
function auth_checkPass($user,$pass){
  global $conf;
  $users = auth_plain_loadUserData();
  if ( empty( $users[$user] )) return false;
  if ( $mbox = @imap_open ($conf['mailserver'], $user, $pass) ){
	imap_close( $mbox );
	return true;
    return false;
 * Return user info [required auth function]
 * Returns info about the given user needs to contain
 * at least these fields:
 * name string  full name of the user
 * mail string  email addres of the user
 * grps array   list of groups the user is in
 * @author  Andreas Gohr <>
function auth_getUserData($user){
  $users = auth_plain_loadUserData();
  return $users[$user];
 * Create a new User [required auth function]
 * Returns false if the user already exists, null when an error
 * occured and the cleartext password of the new user if
 * everything went well.
 * The new user HAS TO be added to the default group by this
 * function!
 * @author  lss <>
 * @modify from  Andreas Gohr <>
function auth_createUser($user,$name,$mail){
  global $conf;
  $users = auth_plain_loadUserData();
  if(isset($users[$user])) return false;
  //we do not need create any password
  //$pass = auth_pwgen();
  $userline = join(':',array($user,
                             "*",	//fill password field with a star(*)
  $userline .= "\n";
  $fh = fopen('conf/users.auth','a');
    return $pass;
  msg('The users.auth file is not writable. Please inform the Wiki-Admin',-1);
  return null;
 * Load all user data
 * Used by the plaintext auth functions
 * loads the user file into a datastructure
 * @author  lss <>
 * @modify from  Andreas Gohr <>
function auth_plain_loadUserData(){
  $data = array();
  $lines = file('conf/users.auth');
  foreach($lines as $line){
    $line = preg_replace('/#.*$/','',$line); //ignore comments
    $line = trim($line);
    if(empty($line)) continue;
    $row    = split(":",$line,5);
    $groups = split(",",$row[4]);
    //usrs.auth stores no more password
    //$data[$row[0]]['pass'] = $row[1];
    $data[$row[0]]['name'] = urldecode($row[2]);
    $data[$row[0]]['mail'] = $row[3];
    $data[$row[0]]['grps'] = $groups;
  return $data;

now, user with mail in mailserver can login use their username/password. in my wiki’s here is more detail write in traditional chinese.

lss 2005-03-17 04:36

TABLES: displaying blank rows

Sometimes its handy to be able to space data out in a table with a blank row. Currently Dokuwiki outputs html for the blank row, however some browsers may not display the row as it has no non-whitespace content. The following change adds a non-breaking space into any empty cell and neatly overcomes the problem.

file: inc/parser.php function: formattable() line: ~ #670

      $data = trim($data);
      if (!$data) $data = '&nbsp;'  // added to prevent empty cells and force browsers to display empty cells/rows
      if ($head) {

Is this change worth a feature request for inclusion in main code base?

Chris 2005-Apr-24

Or you could also try this in the table itself:

|| \\ ||||

(four column table in line above , but needs five definitions.)

hack <3

btw. dokuwiki doesn´t parse the %% tags right regarding multiple spaces. FIXME

qriff 2005-06-19

USER AUTH: setting password

if you have enough rights on the server to manually edit your conf/user.auth, and you’re using ‘plain’ authentication, you can set a new password. the password string in conf/user.auth is a php md5 hash. on linux, I can get an md5 hash of a string by typing

$ echo -n mynewpassword | md5sum 

on the command line. copy and paste the output into user.auth and test it.
ofcourse you made a backup :)

Pike 2005-Apr-27

or use a bash script:

if [ ! -z "$5" ]
  echo $1:`echo -n $2 | md5sum | cut -d \  -f1`:$3:$4:$5 >> /path/to/users.auth
  echo "USAGE:"
  echo "  addDokuUser user pass \"Real Name\" email groups"

Local links with icons

Note: there may be an easier way to do this. But I couldn’t find one, - so here goes:
To display internal links with a nice icon (like dokuwiki does on this site), you can add an interwiki namespace

local     ./

in conf/interwiki.conf. You can then write links like


and they will show up as an interwiki link:
If you configured interwiki links to open in new windows, your ‘local’ links will open in a new window too :-|

Pike 2005-Apr-29

Links to dokuwiki commands

Dokuwiki ‘commands’ like ‘login’,’register’ etc are usually available through buttons in the interface. If you want to display them as links in your text you can add an interwiki namespace

do     ./?do={URL}

in conf/interwiki.conf. You can then write links like


and it will show up as an interwiki link:
If you configured interwiki links to open in new windows, your ‘command’ links will open in a new window too :-|

Pike 2005-Apr-29

E-Razor: You’ll have to use these lines when not using mod_redirect:
do     ./doku.php?do={URL}

Having an image instead of title text in the upper-right corner

You can see this one in action here:

in tpl/default/main.php change:

        <?tpl_link(wl(),$conf['title'],'name="top" accesskey="h" title="[ALT+H]"')?>


        <?tpl_link(wl(),$conf['logo'],'name="top" accesskey="h" title="[ALT+H]"')?>

and in config/dokuwiki.php add a new variable:

$conf['logo']       = '<img src="media/yourlogo.png" alt="Logo" />';

The additional variable is neccesary because otherwise the “<img...>” would be shown in the HTML <title> Tag...

Have fun! peace, Christoph Neuroth 2005-05-08

Hide inaccessible dirs/namespaces in indexes

When user clicks on Index, he sees all the directories (namespaces), but not all the pages - only the ones which he has access to.
Here is the patch to hide directories/namespaces also:

In file inc/search.php, in function search_index, around line 86, replace this code:

  if($type == 'd' && !preg_match('#^'.$file.'(/|$)#','/'.$opts['ns'])){
    //add but don't recurse
  }elseif($type == 'f' && !preg_match('#\.txt$#',$file)){
    //don't add
    return false;

with this updated version:

  if($type == 'd' && !preg_match('#^'.$file.'(/|$)#','/'.$opts['ns'])){
    //add but don't recurse
    $return = false;
// FIX - hide inaccessible directories/namespaces in indexes
    if(auth_quickaclcheck(str_replace('/',':',substr($file,1)).':')<AUTH_READ) {
  }elseif($type == 'f' && !preg_match('#\.txt$#',$file)){
    //don't add
    return false;

miko 2005-05-12 14:30

Please note that this has some logic problems. It is possible to make all documents in a namespace not readable by default but make some of its documents or even a whole subnamespace readable. If you apply the patch above, you will not be able to see these documents or subnamespaces in the index. — Andreas Gohr 2005-05-12 23:02

Including Code in Ordered Lists

Silly, but it took me a while to figure out. Use the dokuwiki code blocks, but make sure the first block is on the same line as the list item.

1) see the VERSION file in the dokuwiki root
tips.txt · Dernière modification: 19/10/2005 17:27
Recent changes RSS feed Creative Commons License Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki