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

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.

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

: 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:

  [[mynewspace:mystartpage]]

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]]

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 > $f.new; done
for f in `ls *.new | sed -e 's:\(.*\)\.new:\1:g'`; do mv $f.new $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 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...

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

$> 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? :: :: 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

I use the following script to make a simple Index.

#!/usr/bin/zsh
cd $1
echo "|Last Update: ^ $(date) ^" > index.txt
foreach line in $(find  . -iname "*txt"|grep -v "\.cache")
  do
        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:*

1. wiki:dokuwiki
2. wiki:playground
3. wiki:syntax

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:

[[/pagename.html]]

or similar.

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

  }elseif(preg_match('#([a-z0-9\-_.]+?)@([\w\-]+\.([\w\-\.]+\.)*[\w]+)#i',$link['url'])){
    // email
    $link = format_link_email($link);
  }else{
    // wiki link
    $link = format_link_wiki($link);
  }

And change it to:

  }elseif(preg_match('#([a-z0-9\-_.]+?)@([\w\-]+\.([\w\-\.]+\.)*[\w]+)#i',$link['url'])){
    // email
    $link = format_link_email($link);
  }elseif(strpos($link['url'],'/') === 0){
  	// absolute URL (for current site)
  	$link = format_link_absoluteurl($link);
  }else{
    // wiki link
    $link = format_link_wiki($link);
  }

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

/**
 * format absolute URLs
 *
 * @author Robert Meerman <robert.meerman@gmail.com>
 * @adapted from the work of Andreas Gohr <andi@splitbrain.org>
 */
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 example.com)

— 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:

mysite    http://myhost.com/{URL}

And then reference any Absolute Link like this:

[[mysite>pagename.html]]

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.

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
  if(!preg_match('#^https?://#i',$src)){
    // 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
  if(preg_match('#^([a-z0-9]+?)://#i',$src)){

to:

  //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:

{{templates:button.gif}}

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:

<?php
    // 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 http://www.php.net/manual/en/function.imap-open.php 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 (http://www.gnu.org/licenses/gpl.html)
 * @author     lss <lsslss@gmial.com>
 * Modify from auth_plain.php from Andreas Gohr <andi@splitbrain.org>
 */
 
 
/**
 * Check user+password [required auth function]
 *
 * Checks if the given user exists and the given
 * plaintext password is authencate by imap_open
 * 
 * @author   lss <lsslss@gmail.com>
 * @modify from  Andreas Gohr <andi@splitbrain.org>
 * @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;
  }
  else
    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 <andi@splitbrain.org>
 */
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 <lsslss@gmail.com>
 * @modify from  Andreas Gohr <andi@splitbrain.org>
 */
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(*)
                             $name,
                             $mail,
                             $conf['defaultgroup']));
  $userline .= "\n";
  $fh = fopen('conf/users.auth','a');
  if($fh){
    fwrite($fh,$userline);
    fclose($fh);
    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 <lsslss@gmail.com>
 * @modify from  Andreas Gohr <andi@splitbrain.org>
 */
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

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 = ' '  // 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.

qriff 2005-06-19

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:

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

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

[[local>wiki:playground]]

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

Pike 2005-Apr-29

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

[[do>revisions]]

and it will show up as an interwiki link:
revisions
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}

You can see this one in action here: http://deshalbfrei.immermusik.de/

in tpl/default/main.php change:

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

to

        <?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

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) {
      return(false);
    };
  }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

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.