Zim - A Desktop Wiki

Config Files

This page documents the various config files used.
Also see preferences for documentation of the preferences dialog.


Freedesktop (Linux etc.)

Zim uses the scheme as laid down in the "XDG Base Directory Specification" as published by freedesktop.org. The default paths are:

XDG_DATA_HOME   = HOME/.local/share/
XDG_DATA_DIRS   = /usr/local/share/:/usr/share/

These can be overloaded with the coresponding environment variables.

When zim writes config files it always uses XDG_CONFIG_HOME. Data files are read only and are searched for in XDG_DATA_HOME and XDG_DATA_DIRS. The installation defaults for config files are also installed in XDG_DATA_DIRS, but these are copied on first use to XDG_CONFIG_HOME.


On Windows the default paths are:


Where APPDATA is the default Windows path to store application data, typically a path like "USERPROFILE\Application Data".

When there is no HOME environment parameter defined on Windows either the USERPROFILE parameter or HOMEDRIVE + HOMEPATH are used. Make sure to define HOME or USERPROFILE including a drive letter.

Global Config Files

These config files determine various aspects of how zim behaves. They are global in the sense that they are not specific for one notebook.

Main config file

The default config file is XDG_CONFIG_HOME/zim/preferences.conf.

The config file is written automatically when you close zim. So if you want to change it manually you need to close all instances of zim first.

There is a hidden option here called "autosave_timeout" which gives the interval for autosaving in seconds, default is 10.

Interwiki URL list

The file XDG_DATA/zim/urls.list gives a list of urls which are used for the interwiki function. All files in the XDG_DATA path are read when looking for an url, so you can use XDG_DATA_HOME to overload the installation defaults.

The format consist of one url per line, each line giving the key (which is the interwiki name), followed by whitespace, followed by the actual url. The url can conatin place holders "{NAME}" or "{URL}", the first will be replaced by the name of the interwiki page, the second by this name in url encoding. If no placeholder is found in the url the url encoded name is appended to the url.

Note that if you want interwiki page to include url syntax like a "#" to link to anchors in the target page, you should write your URLs with "{NAME}".

As a special case you can add other zim notebooks in the url list using "zim+file://" as URL scheme. These URLs will trigger zim to open the notebook directly.

Date format list

The file XDG_DATA/zim/dates.list gives a list of strftime formats, one on each line, to be used to populate the "Insert Date and Time" dialog. The first instance of this file that is found in the XDG_DATA path is used.

See this link for documentation of the strftime formatting.

Automount config file

The config file XDG_CONFIG_HOME/zim/automount.conf can be used to configure mount commands for specific notebook paths. See Automount for details.

GUI style config file

Zim has certain defaults on how to display styles. For example it displays links as blue text without underline. To change this style copy "/usr/share/zim/style.conf" to "~/.config/zim/" and edit it. Each style has it's own section which starts with the style name between square brackets and contains key value pairs for the various display properties.

NOTE: The display styles for the GUI are not used when exporting to HTML. If you want your HTML to show certain custom styles you should write a HTML template with a CSS stylesheet.


tabs = 40
font = Sans 10

[Tag bold]

[Tag italic]
style = italic

Known properties for TextView:

Known style tags:

Known properties for Tags:

Gtk configuration

To change the look of the application beyond what can be done with the style.conf file you need to modify the Gtk theming. With Gtk3 this can be done using the CSS language similar to how e.g. webpages are styled.

The file location of this configuration is: $XDG_CONFIG_HOME/gtk-3.0/gtk.css . You need to re-start zim to see it take effect. For examples of common things, like changing font or color please use you search engine of choice. The developer documentation is here: https://developer.gnome.org/gtk3/stable/GtkCssProvider.html

In addition there are some settings that are not in CSS but can be configured via $XDG_CONFIG_HOME/gtk-3.0/settings.ini . The developer documentation is here: https://developer.gnome.org/gtk3/stable/GtkSettings.html

There are some widgets in zim that have a name set, so they can be addressed specifically from the CSS style using an id selector ("#name").

Specific ones are:

More names are documented in the manual page of specific plugins.

To identify these in the code, search for use of widget_set_css(...) and widget.set_name(...). The name used will be accessible from the CSS config as an "id".

Another way to identify CSS selector IDs is to use GTK Inspector, which can be invoked when calling Zim from the command line as follows:

GTK_DEBUG=interactive zim

CSS configuration examples

The following snippets that can be used directly in ~/.config/gtk-3.0/gtk.css

#zim-pageview text {
    background-color: #1A2E38;  /* changes the background color of the Zim's page editor */
    color: #BABABA; /* foreground text color */

#zim-toc-widget {
  color: #2b2b2b;  /* sets the color of the border line of the Table of Content plugin */
  opacity: 0.9;    /* give the ToC some nice transparency */
  font-size: 12px; /* ToC font size */

#zim-toc-widget scrolledwindow treeview {
  color: #BABABA;  /* sets the color of the text within the Table of Content plugin */
  opacity: 1;

Notebook config file

There is a notebook specific config files called "notebook.zim" which should be in the notebook folder. This file contains a section "[Notebook]" which contains the properties that can be set in the properties dialog.

One hidden property is "end_of_line" which determines the end-of-line convention for files written by zim within the scope of this notebook. The value can be either "dos" or "unix". For newly created notebooks this value is set depending on the platform on which zim is running. Main purpose of this property is to ensure that a notebook which is shared between e.g. linux and windows machines does not change the full file on every write. When desired the property can be changed manually, which will affect all pages edited after the change.

A second hidden option is "disable_trash" which defaults to False. If enabled this will cause zim to avoid using the system trash for this notebook, see the section about deleting in Pages.

A third hidden option is "shared" which defaults to True (however will be False for older notebooks). If True, zim stores the notebook cache in the home folder (XDG_CACHE_HOME). Usually this is what you want, however in particular cases, e.g. when the notebook resides in an encrypted folder, you may want to set this to False in order to make sure the cache is actually stored in the notebook folder (using a ".zim" hidden folder).