Zettelstore boxes

Zettelstore must store its zettel somewhere. In most cases you want to store your zettel as files in a directory. Under certain circumstances you may want to store your zettel elsewhere.

An example is the predefined zettel that come with Zettelstore. They are stored within the software itself. In another situation you may want to store your zettel in volatile memory, e.g. if you want to provide a sandbox for experimenting.

To cope with these (and more) situations, you configure Zettelstore to use one or more boxes. This is done using the box-uri-X keys of the startup configuration (X is a number). Boxes are specified using special URIs, similar to web addresses.

The following box URIs are supported:

dir://DIR

Specifies a directory where zettel files are stored. DIR specifies the path to the directory. You can use a relative file path, such as ./zettel (→ URI is dir://./zettel), but in most cases an absolute file path is recommended, e.g. /home/user/zettel.

The directory must exist before starting Zettelstore¹.

It is possible to configure a directory box.

file:FILE.zip or file:///path/to/file.zip

Specifies a ZIP file that contains files that store zettel. You can create such a ZIP file, if you zip a directory full of zettel files.

This box is always read-only.

mem:

Stores zettel in volatile memory. If you stop Zettelstore, all changes are lost. To limit usage of volatile memory, you should configure this type of box, although the default values might be appropriate for your use case.

All boxes that you configure via the box-uri-X keys form a chain of boxes. When Zettelstore retrieves a zettel, a search starts in the box specified with the box-uri-1 key, then box-uri-2 and so on. If a zettel is created or changed, it is always stored in the box specified with the box-uri-1 key. This allows you to overwrite zettel from other boxes, e.g. the predefined zettel.

Every box has a unique “name”. The name of a box can be assigned if you set the URI query parameter name to its desired value. It is an error if you give the same name twice. If no query parameter name is given, Zettelstore checks whether the URI scheme can be used as a unique name. As a last resort, a name is calculated by the URI position, and optionally made unique by adding the value of another counter.

If you use the mem: box, where zettel are stored in volatile memory, it only makes sense if you configure it as box-uri-1. Such a box will be empty when Zettelstore starts, and only the first box will receive updates. You must ensure that your computer has enough RAM to store all zettel.

1. There is one exception: when Zettelstore is started without any parameter, e.g. via double-clicking its icon, a directory called ./zettel will be created. ↩︎