DokuWiki 使用指南

作者: 梁如军 (Osmond Liang)
Initial Version: 0.1 (2006/05/25)
Current Version: 1.0 (2006/05/30)

内容提要

  1. DokuWiki 简介
  2. 安装配置完全开放的 DokuWiki
  3. 安装配置写受限的 DokuWiki
  4. 使用带有 sidebar 的 “arctic” Template
  5. 常用的插件、插件安装的一般方法
  6. Blog 插件和 Backlinks 插件的使用

版权声明

前言

使用文本文件存储内容的 Wiki 在 安装/备份/移植 等方面都非常方便。典型的基于文本文件的 Wiki 引擎有:

参考

我选用 DokuWiki,主要原因有:

  • 具有丰富的页面表现力,适合书写 “指南”、“教程”
  • 我的虚拟主机空间只支持 PHP :-(

愿本指南能为您使用 DokuWiki 提供些帮助 :-)

关于 DokuWiki

安装 DokuWiki 的系统要求

服务器

  1. 具有 PHP 支持的 Web 服务器
  2. PHP 的要求
<?php phpinfo(); ?>

info.php

DokuWiki 使用文本文件存储数据,无需数据库支持。

浏览器

参考

安装 DokuWiki

下载

当前的稳定版是 dokuwiki-2006-03-09,为了使用一些新的插件,本指南使用的是开发版本 dokuwiki-2006-05-22

基本安装

  1. 将下载的压缩包解压
  2. 创建 data/changes.log 空文件
  3. 创建 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

conf/local.php

最后将整个解压目录上传至服务器即可。

  1. 要保证 Web 服务器对 data 目录可写,如果上传用户不是 Web 服务器进程的用户需要适当调整权限。
  2. 执行基本安装之后,所有的用户都可 读/写 本 Wiki 的内容,这正符合 Wiki 的精神。

参考

配置用户访问控制

配置用户访问控制涉及如下的三个配置文件:

  1. conf/local.php — 用于启用访问控制
  2. conf/users.auth.php — 用于存储用户信息
  3. conf/acl.auth.php — 用户设置用户的访问控制

users.auth.php 文件的格式

users.auth.php 文件的格式与 UNIX/Linux 的 /etc/passwd 文件的格式很类似。

  • 每一行说明一个用户的信息
  • 每一行由如下字段组成,并以 : 间隔
    1. user — 登录用户名
    2. MD5password — MD5加密的口令
    3. Real Name — 用户全名
    4. email — 用户 E-mail 地址
    5. groups — 用户所属的组

acl.auth.php 文件的格式

  • 每行声明一条访问控制规则
  • 每行由如下三个字段组成,并以 空格/Tab 间隔
    1. 指定文件
      • * — 表示所有文件
      • 可以使用名字空间 — 如 blog:* 表示 blog 名字空间中的所有文件,即 data/pages/blog 目录下的所有文件
    2. 指定用户或组
      • @ALL — 表示所有用户
      • @users — 表示 users
      • user — 表示名为 user 的用户
    3. 指定权限
      • 0 — 无权限
      • 1 — 读
      • 2 — 编辑
      • 4 — 创建
      • 8 — 更新

大数值的权限包含了小数值的权限,例如:4 表示可创建、可编辑、可读。

用户访问控制配置举例

本例将设置两个可写用户 osmond 和 jason,两人都属于 user 组,其中 osmond 是管理员(添加到 admin 组)。

创建 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

users.auth.php 文件举例

MD5password 字段的获得:

  • 若您有 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''  目录)的权限

acl.auth.php 文件举例

编辑 local.php 文件

打开 conf/local.php 文件,添加如下内容

$conf['useacl']       = 1;
$conf['superuser']   = '@admin';
$conf['passcrypt']   = 'md5';
$conf['openregister'] = 0;

配置 conf/local.php 文件

admin 组的用户登录后可以进入 Web 管理界面,对 DokuWiki 进行进一步设置。

参考

配置 rewrite

配置 rewrite 涉及如下的两个配置文件:

  1. conf/local.php — 用于启用 rewrite
  2. .htaccess — 用于设置 rewrite 规则

启用 rewrite

要启用 rewrite 功能需要在 conf/local.php 文件中添加如下的行:

$conf['userewrite']   = n;                       //(n 的默认值为 0)

在 ''conf/local.php'' 中启用 rewrite

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

  1. 若服务器不支持 mod_rewrite 模块 (如:E 动网的虚拟主机),请使用 $conf['userewrite'] = 2;
  2. 如果您对 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

.htaccess 文件

参考

使用 DokuWiki

DokuWiki 语法

用 wiki 语法编辑,参见 DokuWiki Syntax, 或安装后自带的语法页面。

您可以查看本页的源码来学习 DoduWiki 的语法,方法是: 单击左上方的 显示源码

使用页面模版

DokuWiki 支持每个命名空间(namespace)的页面模版。namespace 映射到文件系统上就是目录,所以可以在 data/pages 下的每个目录中分别创建该 namespace 下所有页面的模版。页面模版的文件名称约定为 _template.txt

由于 DokuWiki 默认情况下不允许编辑以 _ 开头的文件,所以要在本地编辑该文件然后上传。

_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 查找并下载模版。

本指南介绍 “arctic” 模版的安装和使用,本指南使用的版本是 2006-05-21

安装 "arctic" Template

  1. 解压缩
  2. 编辑 conf/local.php 文件,添加如下的行
$conf[’template’] = ‘arctic’;

配置 conf/local.php 文件

将整个 “arctic” 目录上传到 lib/tpl/ 目录下即可。

可以编辑 arctic 目录下的 style.ini 文件改变显示外观。

参考

使用 "arctic" Template

“arctic” Template 支持 sidebar,使用方法是在 data/pages/ 目录下创建名为 sidebar.txt 的文件,在该文件中可以使用 Wiki 语法设置链接进行导航。

参考

安装使用 Plugin

DokuWiki 支持 Plugin (插件)。可以到 DokuWiki Plugins 查找并下载插件。

插件的一般安装方法

  1. 下载
  2. 解压
  3. 将解压后的文件夹上传到 lib/plugins 目录下
  4. 根据需要修改模版 (并非所有插件都需要此步骤)

常用的插件

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

lib/tpl/arctic/main.php

然后找到并修改如下的部分

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

lib/tpl/arctic/main.php

修改 Blog 插件的配置文件

修改 lib/plugins/blog/conf/default.php 。

主要修改如下的行:

$conf['blog_namespace']   = 'blog';                  // 设置 blog 的所有文章存放的 namespace
$conf['tag_namespace']    = 'blog:categories';       // 设置 blog 的 Tags 存放的 namespace

修改 lib/plugins/blog/conf/default.php

参考

配置 Exclude Pages

修改 conf/local.php, 添加如下的行

$conf['hidepages']   = 'start|sidebar';               //Regexp for pages to be skipped from RSS, Search and Recent Changes

修改 conf/local.php

Blog 插件的使用方法

创建 Blog 主页面

修改主页文件 start 或创建一个 Blog 链接页面,在页面中填写如下内容

~~NOTOC~~
{{blog>blog:2006?10}}
创建 Blog 文章模版

在 data/pages/blog/2006/ 目录下创建 _template.txt,内容如下:

====== @PAGE@ ======



{{tag>}}

~~DISCUSSION~~
创建 Blog 文章
  1. 首先以可写的用户登录系统,然后在 Blog 主页面中的 New blog entry: 后输入文章标题,之后单击 创建本页
  2. 用 Wiki 语法写 Blog 的内容
  3. 在 {{tag>}} 的 > 之后填写以空格间隔的 Tags
  4. 编辑后保存
创建 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 页面存放在 blog namespace 下,Blog 的 Tags 存放在 blog:categories namespace 下。也就是说,Blog 的 Tags 只是针对 BLOG 文章的。
  • 如果要让普通的 Wiki 页面支持 Tags 就需要使用 Backlinks 插件的功能。思路是:
    1. 在写 Wiki 页面时添加指定的 Tags 页面链接
    2. 在指定的 Tags 页面中使用 ~~BACKLINKS~~ 显示链接到当前页面的所有页面的列表

Backlinks 插件的使用方法

创建 Tags 主页面

修改主页文件创建一个 tag 主页面,在页面中填写如下内容

<< [[:sitemap]]\\
<< [[:start]]\\
====== Tags ======

~~BACKLINKS~~
创建 Wiki 页面

创建 Wiki 页面时,在页首添加 Tags 链接。例如:要创建 ubuntudappernetdevsrvapt 四个 Tags,就要在 Wiki 页面中添加如下四个 Tags 链接。

**Tags:** [[:tag:ubuntu]], [[:tag:dapper]], [[:tag:netdevsrv]], [[:tag:apt]]

然后书写 Wiki 页面的正文。

如果在某个 namespace 里的文章的相关 Tags 一样或类似,可以修改这个 namespace 的模版文件 _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

在每个页面中显示阅读次数。需要执行如下步骤:

  1. data/pages/ 目录下创建名为 _cache 的子目录
  2. 修改权限,保证 Web 服务器对该目录可写
  3. 修改 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 ' &middot; ';
    print $lang['lastmod'];
    print ': ';
    print $date;
    if($INFO['editor']){
      print ' '.$lang['by'].' ';
      print $INFO['editor'];
    }
    if($INFO['locked']){
      print ' &middot; ';
      print $lang['lockedby'];
      print ': ';
      print $INFO['locked'];
    }
  }
}

替换前的 ''function tpl_pageinfo()'' 函数

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 ' &middot; ';
    print $lang['lastmod'];
    print ': ';
    print $date;
    if($INFO['editor']){
      print ' '.$lang['by'].' ';
      print $INFO['editor'];
    }
    if($INFO['locked']){
      print ' &middot; ';
      print $lang['lockedby'];
      print ': ';
      print $INFO['locked'];
    }
  }
}

替换后的 ''function tpl_pageinfo()'' 函数

参考

Dokuwiki Backup

  • Bookmark at
  • Bookmark "DokuWiki 使用指南" at del.icio.us
  • Bookmark "DokuWiki 使用指南" at Digg
  • Bookmark "DokuWiki 使用指南" at Furl
  • Bookmark "DokuWiki 使用指南" at Reddit
  • Bookmark "DokuWiki 使用指南" at Ask
  • Bookmark "DokuWiki 使用指南" at BlinkList
  • Bookmark "DokuWiki 使用指南" at blogmarks
  • Bookmark "DokuWiki 使用指南" at Blogg-Buzz
  • Bookmark "DokuWiki 使用指南" at Google
  • Bookmark "DokuWiki 使用指南" at Ma.gnolia
  • Bookmark "DokuWiki 使用指南" at Netscape
  • Bookmark "DokuWiki 使用指南" at ppnow
  • Bookmark "DokuWiki 使用指南" at Rojo
  • Bookmark "DokuWiki 使用指南" at Shadows
  • Bookmark "DokuWiki 使用指南" at Simpy
  • Bookmark "DokuWiki 使用指南" at Socializer
  • Bookmark "DokuWiki 使用指南" at Spurl
  • Bookmark "DokuWiki 使用指南" at StumbleUpon
  • Bookmark "DokuWiki 使用指南" at Tailrank
  • Bookmark "DokuWiki 使用指南" at Technorati
  • Bookmark "DokuWiki 使用指南" at Live Bookmarks
  • Bookmark "DokuWiki 使用指南" at Wists
  • Bookmark "DokuWiki 使用指南" at Yahoo! Myweb
  • Bookmark "DokuWiki 使用指南" at BobrDobr
  • Bookmark "DokuWiki 使用指南" at Memori
  • Bookmark "DokuWiki 使用指南" at Faves
  • Bookmark "DokuWiki 使用指南" at Favorites
  • Bookmark "DokuWiki 使用指南" at Facebook
  • Bookmark "DokuWiki 使用指南" at Newsvine
  • Bookmark "DokuWiki 使用指南" at Yahoo! Bookmarks
  • Bookmark "DokuWiki 使用指南" at Twitter
  • Bookmark "DokuWiki 使用指南" at myAOL
  • Bookmark "DokuWiki 使用指南" at Slashdot
  • Bookmark "DokuWiki 使用指南" at Fark
  • Bookmark "DokuWiki 使用指南" at RawSugar
  • Bookmark "DokuWiki 使用指南" at LinkaGoGo
  • Bookmark "DokuWiki 使用指南" at Mister Wong
  • Bookmark "DokuWiki 使用指南" at Wink
  • Bookmark "DokuWiki 使用指南" at BackFlip
  • Bookmark "DokuWiki 使用指南" at Diigo
  • Bookmark "DokuWiki 使用指南" at Segnalo
  • Bookmark "DokuWiki 使用指南" at Netvouz
  • Bookmark "DokuWiki 使用指南" at DropJack
  • Bookmark "DokuWiki 使用指南" at Feed Me Links
  • Bookmark "DokuWiki 使用指南" at funP
  • Bookmark "DokuWiki 使用指南" at HEMiDEMi
guide/history/dokuwiki-2006-05-30.txt · 最后更改: 2007/03/25 13:31 由 osmond
Recent changes RSS feed Creative Commons License Donate Driven by DokuWiki