====== Tips and Tricks ======
This is the place to collect all your little Tips and Tricks for [[DokuWiki]] Usage.
===== Usage Tips =====
^ Link ^ Short Description ^
| [[wiki:tips:TailorWikiRules]] | How to adjust DokuWiki to fit your needs |
| [[http://www.robmeerman.co.uk/unix:unison|Syncing with Unison]] | Sync two wikis using unison |
| [[wiki:tips:timezone]] | Set the server's Timezone |
| [[wiki:tips:mailconfig]] | Tips on making mail work |
===== Extending the Syntax =====
Most of these tips need to be adjusted for the new [[wiki:Parser]] and will not work out of the box. They may be better implemented by using the new [[wiki:plugin]] system though. A list of plugins using the new plugin interface lives at the [[wiki:plugin]]-page.
^ Link ^ Short Description ^
| [[http://setiwiki.tammen.net/latexrender|LatexRender]]| Render LaTeX-fragments to images, can be used as an alternative to MathML |
| [[wiki:tips:reverseheadertags|Invert Headers]] | Inverts the syntax for Headline (i.e., '=' = H1, '==' = H2, etc |
| [[wiki:tips:tableswithrowspans|Tables with Rowspans]] | Support for columns to cross rows ( rowspans ) in tables using new syntax. |
| [[wiki:tips:Echo PHP variables securely]] | Display predefined variables in pages |
| [[http://mikezornek.com/archives/2005/02/12/how_i_added_markdown_to_dokuwiki.php|Markdown]]| Adding Markdown to DokuWiki |
| [[wiki:tips:SVG Support]] | Collaborate on vector images using the SVG format |
| [[http://chrislee.dhs.org/wiki/doku.php?id=wiki:graphviz_support|GraphViz Support]] | Collaborate on graphs |
| [[wiki:tips: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 [[wiki:tpl:template]] mechanism. You are encouraged to rewrite them accordingly.
^ Link ^ Short Description ^
| [[wiki:tips:CustomQuoting]] | Change the style of Quoting |
| [[http://ktyp.com/dev/doku/dokuwiki/hacks/hidephp|Hide php Code]] | Hide code in %%...%% tags when the user doesn't have permission to edit the page. |
| [[wiki:tips:format_user]] | Using CN from client certificate when displaying username |
| [[wiki:tips:fold_support|Folding Sections]] | Allows sections of text to be folded (shown or hidden by user interaction) |
| [[wiki:tips:Folding Sections Revisited]] | A variation on the above tip |
| [[wiki:tips:HierarchicalBreadcrumbs]] | Another aproach on breadcrumbs navigation |
| [[http://ktyp.com/dev/doku/dokuwiki/hacks/prettyrecent|Pretty Recent]] | Changes the recently updated page to include day headers [[wiki:tips:prettyrecentfix|Fix for July 1 Revision]]|
| [[wiki:tips:smiley toolbar]] | Add a smiley toolbar |
| [[wiki:tips:underscores|Underscores to blanks]] | Convert Underscores back to blanks in titles |
| [[wiki:tips:prewithwrap|'pre' section with wrap]] | %%%% section with wrapping |
===== Adding new Functionality =====
^ Link ^ Short Description ^
| [[wiki:tips:ResetPassword]] | Reset password for a user in auth_plain |
| [[wiki:tips:AllowUserToSetPassword]] | Allows the user to define the password to use for login, instead of receiving it by e-mail. |
| [[wiki:tips:editformtips|Edit Form Mods]] | Extend the Editform |
| [[wiki:tips:BrowserLanguageDetection]] | Change the UI language automatically |
| [[wiki:tips:namespaceindex]] | Show the index of a namespace when browsing to a namespace |
| [[http://www.akehrer.com/wiki/dokuwiki_calendar|Calendar]]| Add a Calendar to Dokuwiki - no way to add comments! and html_head(); is undeclared! |
| [[wiki:tips:JSCalendar]] | Create a DokuWiki-Calendar |
| [[wiki:tips:pdfexport|PDF Export]] | PDF export using html2ps and pstopdf |
| [[http://wiki.erazor-zone.de/doku.php?id=wiki:projects:php:dokuwiki:counter|View Counter]] | Count Page Views |
| [[http://wiki.erazor-zone.de/doku.php?id=wiki:projects:php:dokuwiki:print_view|Print View Button]] | make use of ?do=export_html |
| [[http://wiki.erazor-zone.de/doku.php?id=wiki:projects:php:dokuwiki:user_link|User Link]] | use an extra wiki-page for users |
| [[wiki:tips:HtaccessAuth|.htaccess Authentication]] | Use .htaccess authentication instead of the login form |
===== Integration in other Software =====
^ Link ^ Short Description ^
| [[wiki:tips:Integrate with phpBB]] | How to integrate DokuWiki with phpBBs authentication |
| [[wiki:tips:Integration with IPB 2.x]] | How to integrate Dokuwiki with IPB 2.x authentification |
| [[http://qwik.kaffeehaus.ch/wikisyntax_in_phpbb-forum_verwenden|Use DokuWiki Syntax in phpBB]] |Use DokuWiki Syntax in phpBB (in German) |
| [[http://cruesl.um.es/wiki/doku.php?id=wiki_crue:auth_mysql_mambo|Integrate with Mambo CMS]] |How to integrate DokuWiki with Mambo CMS (Spanish) |
===== Interacting scripts and tools =====
^ Link ^ Short Description ^
| [[wiki:tips:Maintainance]] | Cronjobs to keep your wiki clean |
| [[http://www.suttree.com/code/wikemail/|Wikemail]] | a script to import email into DokuWiki |
| [[:sys2wiki.sh]] | Dumps some hardware info in DokuWiki format |
| [[http://homepages.paradise.net.nz/hillview/OOo/|OpenOffice Macro]] | converts an OpenOffice document to DokuWiki format |
| [[http://www.wakatara.com/blog/index.php/archives/2005/01/17/on-collaborative-simplicity-and-the-word2dokuwiki-macro/|Word Macro]] | converts an MS Word document to DokuWiki format |
| [[wiki:tips:Backup Script]] | A small shellscript to backup your wiki data and media, including rotation. |
| [[wiki:tips:UpgradeScript]] | A small script to make DokuWiki updates simpler |
| [[wiki:tips:HTMLtoWiki]] | How to convert HTML to Dokuwiki [[wiki:syntax]] |
| [[wiki:tips: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.
==== Namespaces ====
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]]%%''
==== 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 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 ====
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 [[http://viewcvs.sourceforge.net/|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 dated((see the ''VERSION'' file in the dokuwiki root)) ''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.
#!/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:***
-[[wiki:dokuwiki|wiki:dokuwiki]]
-[[wiki:playground|wiki:playground]]
-[[wiki:syntax|wiki:syntax]]
==== 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:
%%[[/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
* @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 example.com)
--- //[[robert.meerman@gmail.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 [[tips#Relative links|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 16x16 ''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
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@gmail.com|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...
==== auth_mail ====
I modify **auth_plain.php** to **auth_mail.php** for authentication with **pop3/imap** server using PHP [[phpfn>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:
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
* 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;
}
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
*/
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(*)
$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
* @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 [[http://web.nlhs.tyc.edu.tw/wiki/thiswiki:useacl|here]] is more detail write in traditional chinese.
--- //[[lsslss@gmail.com|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 = ' ' // 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@knowledge.teevee|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@bombsquad.org|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 [[http://nl3.php.net/manual/en/function.md5.php| 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@kw.nl|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
==== 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
[[local>wiki:playground]]
and they will show up as an interwiki link: \\
[[local>wiki:playground]] \\
If you configured interwiki links to open in new windows, your
'local' links will open in a new window too :-|
[[pike@kw.nl|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
[[do>revisions]]
and it will show up as an interwiki link:\\
[[do>revisions]] \\
If you configured interwiki links to open in new windows, your
'command' links will open in a new window too :-|
[[pike@kw.nl|Pike]] //2005-Apr-29//
>[[http://wiki.erazor-zone.de/doku.php?id=wiki:users:e-razor|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: http://deshalbfrei.immermusik.de/
in tpl/default/main.php change:
to
and in config/dokuwiki.php add a new variable:
$conf['logo'] = '
';
The additional variable is neccesary because otherwise the "" would be shown in the HTML 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:
<code php>
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;
}
</code>
with this updated version:
<code php>
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;
}
</code>
--- //[[miko@wp.pl|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. --- //[[andi@splitbrain.org|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.