Structure of Zettelstore
Zettelstore is a software that manages your zettel. Since every zettel must be readable without any special tool, most zettel has to be stored as ordinary files within specific directories. Typically, file names and file content must comply to specific rules so that Zettelstore can manage them. If you add, delete, or change zettel files with other tools, e.g. a text editor, Zettelstore will monitor these actions.
Zettelstore provides additional services to the user. Via the builtin web user interface you can work with zettel in various ways. For example, you are able to list zettel, to create new zettel, to edit them, or to delete them. You can view zettel details and relations between zettel.
In addition, Zettelstore provides an “application programming interface” (API) that allows other software to communicate with the Zettelstore. Zettelstore becomes extensible by external software. For example, a more sophisticated user interface could be built, or an application for your mobile device that allows you to send content to your Zettelstore as new zettel.
Where zettel are stored
Your zettel are stored typically as files in a specific directory. If you have not explicitly specified the directory, a default directory will be used. The directory has to be specified at startup time. Nested directories are not supported (yet).
Every file in this directory that should be monitored by Zettelstore must have a file name that begins with 14 digits (0-9), the zettel identifier. If you create a new zettel via the web user interface or via the API, the zettel identifier will be the timestamp of the current date and time (format is YYYYMMDDhhmmss). This allows zettel to be sorted naturally by creation time.
Since the only restriction on zettel identifiers are the 14 digits, you are free to use other digit sequences. The configuration zettel is one prominent example, as well as these manual zettel. You can create these special zettel by manually renaming the underlying zettel files.
It is allowed that the file name contains other characters after the 14 digits. These are ignored by Zettelstore.
Two filename extensions are used by Zettelstore:
- .zettel is a format that stores metadata and content together in one file,
- the empty file extension is used, when the content must be stored in its own file, e.g. image data; in this case, the filename just the 14 digits of the zettel identifier, and optional characters except the period ".".
Other filename extensions are used to determine the “syntax” of a zettel. This allows to use other content within the Zettelstore, e.g. images or HTML templates.
For example, you want to store an important figure in the Zettelstore that is encoded as a .png file. Since each zettel contains some metadata, e.g. the title of the figure, the question arises where these data should be stores. The solution is a meta-file with the same zettel identifier, but without a filename extension. Zettelstore recognizes this situation and reads in both files for the one zettel containing the figure. It maintains this relationship as long as these files exists.
In case of some textual zettel content you do not want to store the metadata and the zettel content in two different files. Here the .zettel extension will signal that the metadata and the zettel content will be put in the same file, separated by an empty line or a line with three dashes (“---”, also known as “YAML separator”).
Predefined zettel
Zettelstore contains some predefined zettel to work properly. The configuration zettel is one example. To render the builtin web user interface, some templates are used, as well as a layout specification in CSS. The icon that visualizes a broken image is a predefined GIF image. All of these are visible to the Zettelstore as zettel.
One reason for this is to allow you to modify these zettel to adapt Zettelstore to your needs and visual preferences.
Where are these zettel stored? They are stored within the Zettelstore software itself, because one design goal was to have just one executable file to use Zettelstore. But data stored within an executable program cannot be changed later1.
To allow changing predefined zettel, both the file store and the internal zettel store are internally chained together. If you change a zettel, it will be always stored as a file. If a zettel is requested, Zettelstore will first try to read that zettel from a file. If such a file was not found, the internal zettel store is searched secondly.
Therefore, the file store “shadows” the internal zettel store. If you want to read the original zettel, you have to delete the zettel (which removes it from the file directory). Now we have two places where zettel are stored: in the specific directory and within the Zettelstore software.
Boxes: alternative ways to store zettel
As described above, a zettel may be stored as a file inside a directory or inside the Zettelstore software itself. Zettelstore allows other ways to store zettel by providing an abstraction called box.2
A file directory which stores zettel is called a “directory box”. But zettel may be also stored in a ZIP file, which is called “file box”. For testing purposes, zettel may be stored in volatile memory (called RAM). This way is called “memory box”.
Other types of boxes could be added to Zettelstore. What about a “remote Zettelstore box”?