Dokuwiki 主题/模板制作

优质

小牛编辑

133浏览

2023-12-01

Dokuwiki主题/模板制作

之前也有写过，不过已经删掉了，因为提到的方法什么的都过时了，很多内容也没说清楚。看评论时发现这方面的东西还是有人需要的，于是决定重新写一遍。对于主题/模板的制作，除了官方文档之外，也可以在符合 Dokuwiki 标准的 starter 模板基础上进行修改，不少不错的模板都是基于它的。和官方文档类似，这里以 Starter 模板为例。

先安装 Starter 模板，并将 lib/tpl/starter 重命名为 lib/tpl/[你的模板名称] (名称应仅包含 a-z 和 0-9)，然后在配置管理器里选择这个新模板。

目录结构

Starter 模板的目录下有不少文件，其中必要的有：

main.php: 主要的页面布局文件，决定我们一般所看到的页面的布局
detail.php: 图片的详细信息页布局
mediamanager.php: 媒体管理器/选择器窗口的布局
style.ini: 样式控制文件，决定每个样式表应用的情形(屏幕、打印等)，并定义一些全站通用的颜色
template.info.txt: 模板的信息文件，包括名字、作者的信息等。

页面布局 (HTML+PHP)

页面布局的三个文件中，通常只需要修改 main.php，因为它影响一般所看到的页面的布局。没有特别需求的话，detail.php 和 mediamanager.php 不必修改，也可以直接复制默认模板的。布局文件是HTML+PHP，可以调用 Dokuwiki 提供的模板函数来显示标题、维基内容等等，也可以调用全局变量。Starter 模板的 main.php 比较复杂，可以先看一个简单的例子

<html>
  <head><title><?php echo $conf['title']?></title></head>
  <body>
    <div class="dokuwiki">
      <?php tpl_content()?>
      <?php tpl_indexerWebBug()?>
    </div>
  </body>
</html>

这会在标题栏显示网站名称，在页面上显示维基的内容。其中 $conf 是一个全局变量，包含 Dokuwiki 的配置信息。而 tpl_content() 是一个模板函数，可以显示带目录的文章内容。另外一个tpl_indexerWebBug()是每个模板都必须有的函数，否则搜索的索引可能无法建立。

模板函数中的 tpl_includeFile() 可以引用模板目录下的其它文件，从而方便用户添加自定义的内容。比如在 main.php 中写

<head>
    <?php tpl_includeFile('meta.html') ?>
</head>

可以将当前目录下的 meta.html 的内容放入。另外，在被引用的文件中也可以使用 PHP 代码。默认模板和 Starter 模板都预先定义了一些钩子，参见 Include Hooks。

页面样式 (CSS)

对于模板的样式，Dokuwiki 会先读取 style.ini 文件 (参考 devel:style.ini)。这个文件决定需要哪些 CSS/LESS 文件以及每个文件应该用于何种情形(屏幕，打印等)，同时对全站通用的颜色占位符进行定义。比如

[stylesheets]
css/basic.css  = screen
css/design.less = screen
css/print.css  = print   [replacements]
__text__ = "#333" ; @ini_text

这表示 css/basic.css 和 css/design.less 将应用于屏幕显示，而 css/print.css 用于打印，同时定义了__text__占位符代表的颜色。之后只需编辑相应的 CSS/LESS 文件就可以了。在 CSS 中使用颜色占位符的示例如下

body {
    color: __text__;   
}

如果是 LESS 则是

body {
    color: @ini_text;
}