Logo

Zim Wiki 中文文档

ZimWiki中文使用和操作说明

模板

Zim在导出页面时使用模板。通过这种方式,您可以例如在zim中编写网站内容,并使用您选择的布局和样式定义将其导出为HTML。

模板也用于初始化新页面。

如果您正在寻找附件的文件模板信息,请参见Attachments #附件

模板编辑器对话框

可以通过菜单项"编辑" -> "模板"访问模板编辑器对话框。它将显示可用模板的列表,并允许您查看和编辑它们。

模板可以是系统默认值,也可以是您主文件夹中的自定义模板。当您编辑它们时,系统会将默认模板复制到您的主文件夹中,然后编辑该副本。再次使用移除功能会删除此自定义版本,但不会影响默认模板。

注意: 如果您尝试编辑(例如)HTML模板,但它在Web浏览器中打开而不是在您的默认文本编辑器中打开,原因很可能是您没有在首选项中明确配置文本编辑器。转到首选项对话框并指定您的文本编辑器。

模板

默认情况下,模板位于/usr/share/zim/templates/~/.local/share/zim/templates。您可以将经常使用的模板添加到那里。要修改模板,请将其复制到~/.local/...目录并进行编辑。

导出模板

有关导出模板的列表,请参见Export #导出 及其子页面。

页面模板

wiki/Default.txt
此模板用于初始化新页面。默认包含带有页面名称和创建页面日期的标题。

wiki/Journal.txt
此模板用于初始化日记部分中的新页面。

模板语法

模板是您要生成的正常文档输出(例如HTML或Latex)与模板指令的组合。普通文本不经修改传递到输出,而指令则被模板处理的输出替换。

模板指令可以有两种形式:

[% some expression %]

<!--[% some expression %]-->

通常使用第一种形式,但第二种形式在HTML或XML模板中可能看起来更好,因为它被其他工具解析为XML注释。

表达式

模板指令中使用的表达式可以是:

True, False, None        # 字面值 true, false 和 none
"string", 'string', 5, 5.0    # 文本或数字
[.., .., ..]            # 列表
variable            # 变量名
variable.name,            # 带命名属性的变量名
mylist.0            # 包含带索引的列表的变量
function(.., ..)        # 函数调用

可以使用以下运算符:

and
or
not
==         # 等于
!=         # 不等于
>         # 大于
>=        # 大于或等于
<         # 小于
<=        # 小于或等于

有效的变量名可以包含字母(a - z)、数字(0 - 9)和下划线(_)。变量名的第一个字符必须是字母。

指令

指令可以是以下之一:

GET
SET
IF expr EL(S)IF expr .. ELSE .. END
FOR var IN expr .. END
FOREACH var = expr ... END
BLOCK name .. END
INCLUDE name or expr -- block or file

指令始终使用大写字母。其中的表达式可以是大写或小写名称。

获取和设置

[% expr %]             # 隐式GET

[% GET expr %]

使用GET,您可以计算表达式,结果将放入输出中。通常,表达式只是一个变量名。

[% SET var = expr %]

使用SET,您可以分配变量。它不会输出到结果中,指令将被移除。

条件语句

[% IF expr %] ... [% END %]    # 条件

[% IF expr %]
...
[% ELSIF expr %]
...
[% ELSE %]
...
[% END %]

在这些构造中,表达式被计算,根据结果,其中一个块会添加到输出中。用于在模板中包含可选输出

循环

[% FOR var IN expr %]        # 循环
...
[% END %]

[% FOREACH var = expr ]
...
[% END %]

在这些指令中,表达式的结果(通常是输入变量)被迭代,对于每次迭代,都会计算块。

在循环内,变量"var"可用,并设置为迭代的结果。

此外,还有一个特殊变量"loop",可用于访问循环状态。它定义了以下属性:

loop.first        True / False
loop.last        True / False
loop.parity        "even"或"odd"
loop.even        True / False
loop.odd        True / False
loop.size        n
loop.max        n-1
loop.index        0 .. n-1
loop.count        1 .. n
loop.outer        外部"loop"或None
loop.prev        前一项或None
loop.next        下一项或None

[% BLOCK name %]
...
[% END %]

[%  INCLUDE name %]

可以在模板中的任何位置定义BLOCK,然后使用INCLUDE语句包含在其他地方。这对于文档中多次重复的模板部分非常有用。请注意,BLOCK始终在顶级作用域中定义,因此您不能将它们放在IF子句中以定义替代版本。BLOCK可以在使用它们的位置之后定义。

如果没有定义名为"name"的块,"name"将被评估为参数。如果参数的值是块名称,则将包含该块。如果参数的值是文件路径,则将进行文件包含。

文件包含

[% INCLUDE "path/to/file.txt" %]

将在模板中包含"file.txt"的内容,并将其解析为模板内容。

只有包含在模板资源中的文件(见下文)才能以这种方式包含。

对象和函数

大多数变量部分表现为对象,这意味着可以对它们调用对象方法。通常支持以下标准(python)对象方法:

字符串:'capitalize','center','count','endswith','expandtabs','ljust','lower','lstrip','replace','rjust','rsplit','rstrip','split','splitlines','startswith','title','upper'

列表:'get','len','reversed','sorted'

字典:'get','keys','values','items','len','reversed','sorted'

支持以下标准(python)函数:len(list)sorted(list)reversed(list)range(start, end)

为所有模板定义的其他函数:

html_encode(text)
格式化HTML编码中的文本

url_encode(text)
格式化URL编码中的文本

strftime(template, date)
格式化日期,请参阅标准库的代码

strfcal(template, date)
格式化周数,接受:

%w 表示根据区域设置的星期几
%W 表示根据区域设置的周数
%Y 表示周所属的年份

模板变量和函数

页面模板

对于新页面,只定义了一个变量:

page
    .name
    .section
    .basename

另请参阅日记插件了解日记页面可用的一些属性

导出模板

导出时使用模板时,导出模板中可以使用以下变量和函数集:

generator
    .name        Zim版本号"Zim x.xx"
    .user        当前用户名

title            页面标题

navigation        链接到其他导出页面(如果未包含在同一输出文件中)
    .home
    .up                    (尚未实现)
    .prev
    .next

links            带有指向其他导出页面(索引、插件等)链接的已排序字典

    link
        .name
        .basename

pages            要导出的所有内容的迭代器(特殊+内容)
    .special    包含要包含的特殊页面的已排序字典(索引、插件等)
     .content    导出到此文件的页面的迭代器(1个或多个)

    page
        .title        第一个标题或页面名称
        .name        页面名称
        .meta        包含元属性的字典(如果有)
        .section    父页面的名称(如果有)
        .basename    不带部分名称的页面名称
        .heading    页面的第一个标题
        .body        完整正文减去第一个标题
        .content    标题+正文
        .headings(max_level)    按标题拆分页面内容

             headingsection
                .level        标题级别
                 .heading    标题文本
                 .body        此标题下的内容
                 .content    Content including the heading

        .links
        .backlinks
        .attachments

            file
                .basename
                .mtime
                .size

options            可以设置控制输出格式的模板选项的字典

函数:

uri(link|file)
将zim链接或文件对象转换为URL

anchor(page)
将输出页面转换为可链接的锚点

resource(filename)
返回模板资源的URL(见下文)

index(section, collapse, ignore_empty)
创建要导出的页面集的页面索引。

section:索引的起始页面 - 默认为顶级(":")
collapse:如果为True,则只有与当前页面相关的分支可见;如果为False,则所有分支可见 - 默认为True
ignore_empty:如果为True,则忽略空页面 — 默认为True

模板选项

对于导出模板,名为"options"的参数允许设置导出格式的选项。您可以在模板中使用以下方式设置选项:


[% options.line_breaks = 'remove' %]

支持以下选项:

HTML

  • options.line_breaks:值应为"default"或"remove",控制段落中的换行符(<br>元素)
  • options.empty_lines:值应为"default"或"remove",控制源中的空行是否应作为<br>元素插入到HTML输出的顶级元素(如段落、标题等)之间。

Latex

  • options.document_type:可以是"report"、"article"或"book"之一。控制使用的标题类型。

模板资源

要向模板添加附加文件,请创建一个与模板同名的文件夹。当使用此模板导出数据时,文件夹中的任何文件(如样式表、图像、javascript文件等)都会一起复制。模板中有一个函数"resource(filename)"用于引用这些文件。例如:

<link rel="stylesheet" href="[% resource('style.css') %]">

导出时,Zim始终包含一些用于复选框列表中的复选框的图像。要自定义这些图像,此文件夹中应有名为"checked-box.png"、"unchecked-box.png"和"xchecked-box.png"的模板资源。

对于Web界面,资源还可以包含"favicon.ico",用作网站的图标。