DokuWiki 使用指南
作者: 梁如军 (Osmond Liang)
Initial Version: 0.1 (2006/05/25)
Current Version: 1.0 (2006/05/30)
内容提要
- DokuWiki 简介
- 安装配置完全开放的 DokuWiki
- 安装配置写受限的 DokuWiki
- 使用带有 sidebar 的 “arctic” Template
- 常用的插件、插件安装的一般方法
- Blog 插件和 Backlinks 插件的使用
版权声明
本文基于 作者署名-非商业性-保持一致 (by-nc-sa) 发布。
前言
使用文本文件存储内容的 Wiki 在 安装/备份/移植 等方面都非常方便。典型的基于文本文件的 Wiki 引擎有:
我选用 DokuWiki,主要原因有:
- 具有丰富的页面表现力,适合书写 “指南”、“教程”
- 我的虚拟主机空间只支持 PHP

愿本指南能为您使用 DokuWiki 提供些帮助
关于 DokuWiki
安装 DokuWiki 的系统要求
服务器
- 具有 PHP 支持的 Web 服务器
- 首选 Apache
- 对 PHP 的要求
- 基于某些 安全考虑 强烈建议使用 PHP 4.3.10 及其以上的版本
- 运行于 PHP 的 Safe Mode
- 运行于 PHP 的 register_globals=off 模式.
- 使用如下 info.php 脚本查看其他 php 运行参数
浏览器
- 跨平台
- GNOME/KDE desktop
- Linux 平台
- Windows 平台
- Mac OS X 平台
安装 DokuWiki
下载
基本安装
- 将下载的压缩包解压
- 创建 data/changes.log 空文件
- 创建 conf/local.php 空文件,添加如下内容
<?php /* This is an example of how a local.php coul look like. Simply copy the options you want to change from dokuwiki.php to this file and change them */ $conf['title'] = 'YourWikiTitle'; // what to show in the title $conf['lang'] = 'zh'; // your language
最后将整个解压目录上传至服务器即可。
- 要保证 Web 服务器对 data 目录可写,如果上传用户不是 Web 服务器进程的用户需要适当调整权限。
- 执行基本安装之后,所有的用户都可 读/写 本 Wiki 的内容,这正符合 Wiki 的精神。
配置用户访问控制
- conf/local.php — 用于启用访问控制
- conf/users.auth.php — 用于存储用户信息
- conf/acl.auth.php — 用户设置用户的访问控制
users.auth.php 文件的格式
- 每一行说明一个用户的信息
- 每一行由如下字段组成,并以
:间隔- user — 登录用户名
- MD5password — MD5加密的口令
- Real Name — 用户全名
- email — 用户 E-mail 地址
- groups — 用户所属的组
acl.auth.php 文件的格式
- 每行声明一条访问控制规则
- 每行由如下三个字段组成,并以 空格/Tab 间隔
- 指定文件
*— 表示所有文件- 可以使用名字空间 — 如
blog:*表示 blog 名字空间中的所有文件,即data/pages/blog目录下的所有文件
- 指定用户或组
- @ALL — 表示所有用户
- @users — 表示
users组 - user — 表示名为
user的用户
- 指定权限
- 0 — 无权限
- 1 — 读
- 2 — 编辑
- 4 — 创建
- 8 — 更新
用户访问控制配置举例
创建 users.auth.php 文件
创建空的 conf/users.auth.php 文件,并添加如下内容
# users.auth.php # <?php exit()?> # Don't modify the lines above # # Userfile # # Format: # # user:MD5password:Real Name:email:groups,comma,seperated osmond:$1$x9k5BihR$cS4S5KdhVRCGJO66Fpk6m1:Osmond Liang:sinosmond@gmail.com:admin,user jason:$1$bdc88902b9abb5c2ad4ca875d7efa06d:Jason Xie:jason@sinoesl.org:user
- 若您有 Linux 系统,可以创建同名用户并设置密码,然后从
/etc/shadow文件中将其拷入 users.auth.php 文件 - 也可以访问 Free online md5 hash calculator 在线生成并将其拷入 users.auth.php 文件
创建 acl.auth.php 文件
创建空的 conf/acl.auth.php 文件,并添加如下内容
# acl.auth.php # <?php exit()?> # Don't modify the lines above # # Access Control # # none 0 # read 1 # edit 2 # create 4 # upload 8 * @ALL 1 # 所有用户只读 * @admin 8 # admin 组对所有文件可写 playground:* @ALL 8 # 所有用户对 playground 命名空间(即 ''data/pages/playground'' 目录)的所有文件可写 users:jason:* jason 8 # jason 对 users:jason 命名空间(即 ''data/pages/users/jason'' 目录)的所有文件可写 devel:* @ALL 0 # 首先设置所有用户对 devel 命名空间(即 ''data/pages/devel'' 目录)没有权限 devel:* @admin 8 devel:* jason 8 # 限制只有 admin 组和 jason 用户可写 devel 命名空间 devel:funstuff jason 0 # 取消 jason 用户对 devel:funstuff 子命名空间(即 ''data/pages/devel/funstuff'' 目录)的权限
编辑 local.php 文件
打开 conf/local.php 文件,添加如下内容
$conf['useacl'] = 1; $conf['superuser'] = '@admin'; $conf['passcrypt'] = 'md5'; $conf['openregister'] = 0;
配置 rewrite
- conf/local.php — 用于启用 rewrite
- .htaccess — 用于设置 rewrite 规则
启用 rewrite
要启用 rewrite 功能需要在 conf/local.php 文件中添加如下的行:
$conf['userewrite'] = n; //(n 的默认值为 0)
n 的取值可以为 0/1/2,含义如下:
| 值 | 说明 | URL 举例 |
|---|---|---|
| 0 | 不使用 rewrite, 此为默认值 | http://example.com/dokuwiki/doku.php?wiki:syntax |
| 1 | 使用 Apache 实现 rewrite,需要修改 .htaccess 文件 | http://example.com/dokuwiki/wiki/syntax |
| 2 | DokuWiki 实现的 rewrite 功能 | http://example.com/dokuwiki/doku.php/wiki/syntax |
$conf['userewrite'] = 1; ,Apache 服务器的配置必须支持 mod_rewrite 模块,这意味着:
- 在主配置文件中必须启用
mod_rewrite模块 - 若在
.htaccess配置 DokuWiki 的 rewrite 规则,需要在主配置文件中使用指令
AllowOverride All
- 如果您对 Apche 服务器有配置权,当然也可以在主配置文件中书写 DokuWiki 的 rewrite 规则。
配置 rewrite 规则
下面以 .htaccess 文件配置 rewrite 规则。
复制 DokuWiki 目录下的 .htaccess.dist 为 .htaccess,并删除文件中的注释 #。
典型的配置文件如下:
## Enable this to restrict editing to logged in users only ## You should disable Indexes and MultiViews either here or in the ## global config. Symlinks maybe needed for URL rewriting. #Options -Indexes -MultiViews +FollowSymLinks ## make sure nobody gets the htaccess files <Files ~ "^[\._]ht"> Order allow,deny Deny from all Satisfy All </Files> ## Comment these rules in if you want to have nice URLs using ## $conf['rewrite'] = 1 - not needed for rewrite mode 2 RewriteEngine on RewriteRule ^_media/(.*) lib/exe/fetch.php?media=$1 [QSA,L] RewriteRule ^_detail/(.*) lib/exe/detail.php?media=$1 [QSA,L] RewriteRule ^_export/([^/]+)/(.*) doku.php?do=export_$1&id=$2 [QSA,L] RewriteRule ^$ doku.php [L] RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule (.*) doku.php?id=$1 [QSA,L] RewriteRule ^index.php$ doku.php
使用 DokuWiki
DokuWiki 语法
使用页面模版
DokuWiki 支持每个命名空间(namespace)的页面模版。namespace 映射到文件系统上就是目录,所以可以在 data/pages 下的每个目录中分别创建该 namespace 下所有页面的模版。页面模版的文件名称约定为 _template.txt。
_ 开头的文件,所以要在本地编辑该文件然后上传。
_template.txt 除了可以使用 wiki 语法之外,还支持如下的变量:
| @ID@ | full ID of the page |
|---|---|
| @NS@ | namespace of the page |
| @PAGE@ | page name (ID without namespace and underscores replaced by spaces) |
| @USER@ | ID of user who is creating the page |
| @NAME@ | name of user who is creating the page |
| @MAIL@ | mail address of user who is creating the page |
| @DATE@ | date and time when edit session started |
屏蔽默认特性
- 默认情况下,DokuWiki 将在系统的
data/cache目录下缓存页面。 若不缓存某页面,则需在编辑页面时将 ~~NOCACHE~~ 写入页首 - 默认情况下,DokuWiki 将显示每页的目录。若不显示某页的目录,则需在编辑页面时将 ~~NOTOC~~ 写入页首
- 有些字符或字符串是 Wiki 的语法字符,若只想显示其本身而不被 Wiki 引擎解析,有两种方法
- 两端使用
%%将内容括起来 - 使用 <nowiki> 和 </nowiki> 将内容括起来
使用 Template
DokuWiki 支持 Template (模版、皮肤)。可以到 DokuWiki Templates 查找并下载模版。
2006-05-21 。
安装 "arctic" Template
- 解压缩
- 编辑 conf/local.php 文件,添加如下的行
$conf[’template’] = ‘arctic’;
将整个 “arctic” 目录上传到 lib/tpl/ 目录下即可。
使用 "arctic" Template
“arctic” Template 支持 sidebar,使用方法是在 data/pages/ 目录下创建名为 sidebar.txt 的文件,在该文件中可以使用 Wiki 语法设置链接进行导航。
安装使用 Plugin
DokuWiki 支持 Plugin (插件)。可以到 DokuWiki Plugins 查找并下载插件。
插件的一般安装方法
- 下载
- 解压
- 将解压后的文件夹上传到 lib/plugins 目录下
- 根据需要修改模版 (并非所有插件都需要此步骤)
常用的插件
- Admin Plugins
- Syntax Plugins
- Behavior Plugins
- Media Plugins
Blog 插件的使用
Blog 插件的特性
- 可以集中显示给定 namespace 下最新的 BLOG 文章
- 支持对每个 BLOG 文章的留言讨论 (支持 Gravatar 头像)
- 支持 BLOG 文章列表显示: monthly, by tag 或 by editor
- 支持 BLOG 文章 Tags
- 支持基于 namespace 的 Feed 和 Tags
- 支持页面的 include
Blog 插件的配置
修改 "arctic" Template
修改 lib/tpl/arctic/main.php 。
首先在文件首添加如下内容:
<?php // include discussion code include(DOKU_PLUGIN.'blog/functions.php'); // we must move the doctype down (unfortunately) - headers need to be first ?>
然后找到并修改如下的部分
<?php if($ACT != 'diff' && $ACT != 'edit' && $ACT != 'preview') { ?> <div class="left_sidebar"> <?php tpl_searchform() ?> <?php tpl_sidebar() ?> </div> <div class="right_page"> <?php tpl_content()?> <?php tpl_discussion()?> // 若使用 left_sidebar,则添加此行 </div> <?php } else { ?> <div class="page"> <?php tpl_content()?> </div> <?php } ?> <?php } else { ?> <?php if($ACT != 'diff' && $ACT != 'edit' && $ACT != 'preview') { ?> <div class="left_page"> <?php tpl_content()?> <?php tpl_discussion()?> // 若使用 right_sidebar,则添加此行 </div> <div class="right_sidebar"> <?php tpl_searchform() ?> <?php tpl_sidebar() ?> </div> <?php } else { ?> <div class="page"> <?php tpl_content()?> </div> <?php } ?> <?php } ?> <?php } else { ?> <div class="page"> <!-- wikipage start --> <?php tpl_content() ?> <!-- wikipage stop --> <?php tpl_discussion()?> // 若不使用 sidebar,则添加此行 </div>
修改 Blog 插件的配置文件
修改 lib/plugins/blog/conf/default.php 。
主要修改如下的行:
$conf['blog_namespace'] = 'blog'; // 设置 blog 的所有文章存放的 namespace $conf['tag_namespace'] = 'blog:categories'; // 设置 blog 的 Tags 存放的 namespace
配置 Exclude Pages
修改 conf/local.php, 添加如下的行
$conf['hidepages'] = 'start|sidebar'; //Regexp for pages to be skipped from RSS, Search and Recent Changes
Blog 插件的使用方法
创建 Blog 主页面
修改主页文件 start 或创建一个 Blog 链接页面,在页面中填写如下内容
~~NOTOC~~
{{blog>blog:2006?10}}
创建 Blog 文章模版
在 data/pages/blog/2006/ 目录下创建 _template.txt,内容如下:
====== @PAGE@ ======
{{tag>}}
~~DISCUSSION~~
创建 Blog 文章
- 首先以可写的用户登录系统,然后在 Blog 主页面中的
New blog entry:后输入文章标题,之后单击 创建本页 - 用 Wiki 语法写 Blog 的内容
- 在 {{tag>}} 的
>之后填写以空格间隔的 Tags - 编辑后保存
创建 Blog 的 Tags 模版
在 data/pages/blog/categories/ 目录下创建 _template.txt,内容如下:
<< [[:sitemap]]\\
<< [[:blog:categories]]\\
====== blog-category: @PAGE@ ======
{{archive>blog:2006?@PAGE@}}
创建 Blog 的 Tags 文件
在 Blog 页面中点击您定义的 Tags,将提示页面不存在,创建页面,引用模版内容,保存即可。
Backlinks 插件的使用
Backlinks 插件的功能
- 显示链接到当前页面的所有页面的列表
- 可以用此插件实现普通 Wiki 页面(非 BLOG 页面)的 Tag 功能
- Blog 插件要求所有的 BLOG 文件和 BLOG Tags 都存放在指定的 namespace 下,例如我在上面配置 Blog 插件时指定所有的 Blog 页面存放在
blognamespace 下,Blog 的 Tags 存放在blog:categoriesnamespace 下。也就是说,Blog 的 Tags 只是针对 BLOG 文章的。 - 如果要让普通的 Wiki 页面支持 Tags 就需要使用 Backlinks 插件的功能。思路是:
- 在写 Wiki 页面时添加指定的 Tags 页面链接
- 在指定的 Tags 页面中使用 ~~BACKLINKS~~ 显示链接到当前页面的所有页面的列表
Backlinks 插件的使用方法
创建 Tags 主页面
修改主页文件创建一个 tag 主页面,在页面中填写如下内容
<< [[:sitemap]]\\ << [[:start]]\\ ====== Tags ====== ~~BACKLINKS~~
创建 Wiki 页面
创建 Wiki 页面时,在页首添加 Tags 链接。例如:要创建 ubuntu、dapper、netdevsrv、apt 四个 Tags,就要在 Wiki 页面中添加如下四个 Tags 链接。
**Tags:** [[:tag:ubuntu]], [[:tag:dapper]], [[:tag:netdevsrv]], [[:tag:apt]]
然后书写 Wiki 页面的正文。
_template.txt,添加相应的 Tags 链接。这样在创建这个 namespace 里的文章时会自动添加这些 Tags 链接,这会很方便。
创建 Wiki 的 Tags 模版
在上面创建 Tags 链接时,所有的 Tags 都存放在 tag namespace 下,为了方便创建每个 Tags 页面,可以在 tag namespace 下创建模版文件 _template.txt,内容如下:
<< [[:sitemap]]\\ << [[:tag]]\\ ====== Tag: @PAGE@ ====== This is a list of pages tagged with keyword "@PAGE@". ~~BACKLINKS~~
创建 Wiki 的 Tags 文件
在 Wiki 页面中点击您定义的 Tags 链接,将提示页面不存在,创建页面,引用模版内容,保存即可。
Tips and Tricks
下面介绍一个本站使用的 Tips。
View Counter
在每个页面中显示阅读次数。需要执行如下步骤:
- 在
data/pages/目录下创建名为_cache的子目录 - 修改权限,保证 Web 服务器对该目录可写
- 修改 DokuWiki 的 inc/template.php 文件,替换其
function tpl_pageinfo()函数
function tpl_pageinfo(){ global $conf; global $lang; global $INFO; global $REV; // prepare date and path $fn = $INFO['filepath']; if(!$conf['fullpath']){ if($REV){ $fn = str_replace(realpath($conf['olddir']).DIRECTORY_SEPARATOR,'',$fn); }else{ $fn = str_replace(realpath($conf['datadir']).DIRECTORY_SEPARATOR,'',$fn); } } $fn = utf8_decodeFN($fn); $date = date($conf['dformat'],$INFO['lastmod']); // print it if($INFO['exists']){ print $fn; print ' · '; print $lang['lastmod']; print ': '; print $date; if($INFO['editor']){ print ' '.$lang['by'].' '; print $INFO['editor']; } if($INFO['locked']){ print ' · '; print $lang['lockedby']; print ': '; print $INFO['locked']; } } }
function tpl_pageinfo(){ global $conf; global $lang; global $INFO; global $REV; global $ID,$ACT; // prepare date and path $fn = $INFO['filepath']; if(!$conf['fullpath']){ if($REV){ $fn = str_replace(realpath($conf['olddir']).DIRECTORY_SEPARATOR,'',$fn); }else{ $fn = str_replace(realpath($conf['datadir']).DIRECTORY_SEPARATOR,'',$fn); } } $fp_views=fopen(realpath($conf['datadir'])."/_cache/$ID.visits",'a+'); if ($fp_views) { fscanf($fp_views,"%i",$views); if (($ACT == 'show') && ($INFO['exists'])) { $views++; ftruncate($fp_views,0); fseek($fp_views, 0); fwrite($fp_views,$views); } $fn.=" ($views views) "; fclose($fp_views); } $fn = utf8_decodeFN($fn); $date = date($conf['dformat'],$INFO['lastmod']); // print it if($INFO['exists']){ print $fn; print ' · '; print $lang['lastmod']; print ': '; print $date; if($INFO['editor']){ print ' '.$lang['by'].' '; print $INFO['editor']; } if($INFO['locked']){ print ' · '; print $lang['lockedby']; print ': '; print $INFO['locked']; } } }








