Zim - a desktop wiki

Templates

Zim uses templates when exporting pages. This way you can for example write your website in zim and export it to HTML using the layout and style definition of you choice.

Templates are also used to initalize new pages.

Templates for export

For a list of templates for exporting see Help:Export and subpages.

Template options

Templates can also set template options that influence the generated output, by setting key-value pairs like in the example below. A list of available template options for a output format can be found at Help:Export and subpages.

Special templates

wiki/Default.txt
This template is used to initialize new pages. The default contains a header with the page name and a the date at which the page was created.

wiki/Calendar.txt
This template is used to initialize new pages in the calendar namespace.

Customizing

Templates are located in /usr/share/zim/templates/ and ~/.local/share/zim/templates by default. You can add templates you use more often there. To modify a template copy it to the ~/.local/... directory and edit it.

Template syntax:

[% var %]                   # interpolates a variable
[%- var %]

# + strip line break before the expression
[% var -%] # + strip line break after the expression
[%- var -%] # + strip line breaks on both sides

[% IF expr %] ... [% END %] # conditionals

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

[% FOREACH name = var ] # loop
... [% name %] ...
[% END %]

[% strftime("%c") %] # current time stamp
[% strftime("%c", var) %] # date from variable

[% options.option_name = value %] # set the template option option_name to value

For the IF and ELIF statements the expression can be either just a variable, in which case it is evaluated boolean, or an equality expression with "==". For example "[% IF page.name == 'foo' %]" is understood. More complex expressions are not supported.

Available variables:

zim.version		# version of zim
notebook.name		# name of the notebook
notebook.interwiki	# interwiki key of the notebook if any

page.name		# complete page name
page.namespace		# namespace
page.basename		# last part of the page name
page.title		# first heading in the page or the basename
page.heading		# first heading in the page
page.body		# content of the page (without the leading heading)
page.links		# list of page objects for pages linked in this page
page.backlinks		# list of page objects for pages linking to this page
page.properties		# dict with page properties

# These special pages have the same properties as the 'page' object
pages.index		# the index page generated when exporting
pages.home		# the home page
pages.next		# the next page in the index (if any)
pages.previous		# the previous page in the index (if any)

options			# dict where format specific options can be set

Functions available:

url(link)

Turns a zim link into an URL

resource(filename)

Returns an URL for a template resource (see below)

strftime(template, date)

Format a date

pageindex(namespace, collapse, ignore_empty)

Creates a page index of a given namespace or the whole notebook

namespace: the starting root - defaults to the top level (":")
collapse: if TRUE only branches related to the current page are visible, if FALSE all branches are visible - defaults to TRUE
ignore_empty: if TRUE empty pages are ignored — defaults to TRUE.

Example: menu(page.namespace, TRUE, FALSE)

Template Resources

To add additional files to the template, create a folder of the same name as the template. Any files in the folder (like style sheets, images, javascript files, etc.) will be copied along when this template is used to export data in zim. There is a function "resource(filename)" to refer to these files in the template.

Zim always includes some images when exporting for the checkboxes used in checkbox lists. To customize these there should be template resources named "checked-box.png", "unchecked-box.png" and "xchecked-box.png" in this folder.

For the web interface the resources can also contain a "favicon.ico" to serve as the favicon of the website.