来写 ikiwiki 的试用报告

大家都知道,无聊的人特点之一是见到好玩的东西就找来玩一玩,ikiwiki 就是新近发现的有趣东西,把我的兴趣:Subversion, Markdown, wiki 的概念整合到了一起,算是 wiki 程序里边思路比较另类的,本来看到要装一堆 Perl Module,不愿意去折腾,但 hlb 说等我的试用报告 (笑),就试着装了装看,发现真的很好玩,值得推荐,所以把装的时候遇到的问题流水帐地记下来,或许对你有用。

说了这么多,那 ikiwiki 究竟是什么呢?它其实是一套 Perl 程序,虽然是用作 wiki,但和一般的 CGI/mod_perl 的 wiki 程序不一样的是,它把所有的 wiki 数据文件用 Subversion 来管理,这样文件的历史记录、备份和并行控制就可以直接把 Subversion 的功能搬来用,这是 ikiwiki 最大的特点。

此外,ikiwiki 有趣的地方还在于它使用了 Markdown 的语法来作标记,相比常用的 wikitext,我觉得 Markdown 实在是人性化得多的标记方式。在 Markdown 的基础上,ikiwiki 做的两个额外的处理就是 wiki 的链接 (CamelCase 或者手动指定) 和子页面的创建。

ikiwiki 还有些好玩的功能,比如当作 blog 来用、支持反向链接 等等,你可以在它的 features 页面中看到,不过我这里是还没有尝试过啦。

哦,顺便提一句,ikiwiki 的作者 Joey Hess 是一位 Debian Hacker,也是 alien, debconf 的作者。

下面开始讲实际的东西。

安装

我测试的环境是 Arch Linux 2.6.16, Perl 5.8.8, lighttpd 1.4.11, subversion 1.3.1。

首先,ikiwiki 需要以下这些 Perl Module:

  1. CGI::Session
  2. CGI::FormBuilder
  3. HTML::Template
  4. Mail::Sendmail
  5. Time::Duration
  6. Date::Parse
  7. HTML::Scrubber

我的经验是,还需要 HTML::Parser,此外,Markdown 可以使用 Text::Markdown 这个 Module。

用 cpan 装完以后,就可以下载一份 tarball,解压。此时,因为我们使用的是 Text::Markdown 提供的 markdown,所以 Ikiwiki/Render.pm 需要作一点小的修改,找到 Markdown::Markdown 那一行,改为:

use Text::Markdown 'markdown';
$content = markdown($content);

然后执行

perl Makefile.PL
make
make install

就完成的安装。现在可以试试 ikiwiki 命令有没有反应了。

配置

接下来是配置过程,视你希望实现什么功能而有不同的繁琐程度。

第一步是 (先装好 Subversion) 创建给 wiki 使用的版本仓库:

svnadmin create /svn/wikirepo
svn mkdir file:///svn/wikirepo/trunk -m create

然后从这个仓库中 checkout 一份当前的版本作为 working copy,放在自己的 home directory 下边:

svn co file:///svn/wikirepo/trunk ~/wikiwc

这样你就可以用默认的模板和配置构建你的第一个 ikiwiki 了:

ikiwiki --verbose ~/wikiwc/ ~/public_html/wiki/ \
    --url=http://host/~you/wiki/

~/public_html/wiki/ 是你的 Web server 分配给你的 HTML 文档目录。完成上边这一步之后,你就可以在这个目录中找到生成的 *.html 文件 (别忘了 ikiwiki 是一个“wiki compiler”),如果配置好了 web server 的 user directory 功能,就可以在 http://localhost/~username/wiki 看到你的 wiki 了。

这里简单说说 lighttpd 的这个配置,默认的 lighttpd 配置文件在 /etc/lighttpd/lighttpd.conf,首先,在 server.modules 变量中打开 "mod_userdir" 模块,然后设置 userdir.path,以上面的情况为例,就应该是:

userdir.path                = "public_html"

当然,输出的目录也不一定要是你的 home directory,只要你的 web server 和你都能访问到的地方都可以啦。

接下来就可以做真正有趣的定制工作了,默认用来创建 wiki 的文件在 /usr/share/ikiwiki/basewiki/,你可以从里面复制一份到 ~/wikiwc/ 作为自己的版本,比如:

cp /usr/share/ikiwiki/basewiki/index.mdwn ~/wikiwc # 复制首页 (Markdown 标记的)
svn add ~/wikiwc/index.mdwn # 加入 svn
$EDITOR ~/wikiwc/index.mdwn # 修改首页文件内容
svn commit ~/wikiwc/index.mdwn -m customised # commit 到 svn repo 中

你发现 Subversion 在这里派上用场了,凡是编辑 wiki 文件其实都在 Subversion 中维护着,这样 Subversion 就能够跟踪每步更改了。

可是我们现在的方式还很原始耶,不能在浏览器中直接编辑 (也许某些人就喜欢这样),每次要打长长的一串命令,于是,一个叫做“配置文件”的东西出来拯救我们了。

先把 ikiwiki 源文件目录下的 doc/ikiwiki.setup 复制一份到你喜欢的地方。然后开始修改这个文件。里面像 wikiname, adminemail 这样的看名字就知道是什么意思。下面是各项的简短说明,详细的可以看 Usage

  • srcdir: 你放 index.mdwn 文件的那个目录
  • destdir: 你输出 html 的那个目录
  • url: wiki 的 URL
  • cgiurl: 用于自动更新 wiki 的 cgi 程序的路径,这个程序是 ikiwiki 自动生成的,看下面的解释
  • svnrepo 和 svnpath: 和前面创建的 repo 符合,在我这里是 /svn/wikirepo 和 trunk

接下来就是最重要的两个设置,为了实现在线编辑,ikiwiki 可以自动生成一个 (编译好的) C CGI 程序,这个程序的位置就在 cgi wrapper 部分指定,你需要设置为一个你的 web server 可以访问得到,而且又能作为 CGI 程序执行的地方,比如我放在 ~/public_html/wiki/ikiwiki.cgi,那么 lighttpd 对应的配置是:

  1. 打开 mod_cgi
  2. cgi.assign 的设置中,加入 ".cgi" => "" (为空表示不使用其他程序解释,直接执行)

同时,这里设置的位置也必须和前面的 cgiurl 属性对应,如果根据我前面的这个设置,对应的 cgiurl 就是 http://localhost/~username/wiki/ikiwiki.cgi

问题在于,只是编辑了还不行,编辑后的结果得生成静态的 HTML 我们才能读啊,CGI 不负责这一步,它是通过一个 svn post-commit 的 hook 程序实现的,这个程序,同样是一个编译好的 C 程序,由 ikiwiki 自动生成,放在哪里应该是无所谓的,不过我这里是放在 /svn/wikirepo/hooks/post-commit

这样就算是设置完毕了,执行 ikiwiki --setup 配置文件路径/配置文件名 可以生成上面提到的两个程序。

小结

其实小结就是要说些坏话… 目前 ikiwiki 还没开始对 UTF-8 的支持,如果你是直接用编辑器来编辑文件的话,那不会有问题,可是如果希望通过 CGI 来在线编辑,它就搞不定了,在它的 TODO List 中也提到了目前对付的方法,如果要全面解决,还是得期待 2.0 啦。

另外,ikiwiki 这样虽然很好玩,尤其是作为个人信息管理的工具,但恐怕还是不能胜任大型的 wiki,像 wikipedia 这样,同时有成百上千人在编辑,编辑后都要 svn commit… 哦,我不敢想象了。

发现一件有趣的事情,如果按照 ikiwiki 网站上给出的图片把第二个 k 反向,这又是一个反着读也一样的名字 🙂

Author: jjgod

A software engineer from China, working on text rendering for a fruit company. Interested in typography and science fiction.

1 thought on “来写 ikiwiki 的试用报告”

Leave a Reply

Your email address will not be published. Required fields are marked *