Layout of a Zettel

A zettel consists of two parts: the metadata and the zettel content. Metadata gives some information mostly about the zettel content, how it should be interpreted, how it is sorted within Zettelstore. The zettel content is, well, the actual content. In many cases, the content is in plain text form. Plain text is long-lasting. However, content in binary format is also possible.

Metadata has to conform to a special syntax. It is effectively a collection of key/value pairs. Some keys have a special meaning and most of the predefined keys need values of a specific type.

Each zettel is given a unique identifier. To some degree, the zettel identifier is part of the metadata..

The zettel content is your valuable content. Zettelstore contains some predefined parsers that interpret the zettel content to the syntax of the zettel. This includes markup languages, like Zettelmarkup and CommonMark. Other text formats are also supported, like CSS and HTML templates. Plain text content is always Unicode, encoded as UTF-8. Other character encodings are not supported and will never be¹. There is support for a graphical format with a text representation: SVG. And there is support for some binary image formats, like GIF, PNG, and JPEG.

Plain, parsed, and evaluated zettel

Zettelstore may present your zettel in various forms, typically retrieved with the endpoint /z/{ID}. One way is to present the zettel as it was read by Zettelstore. This is called “plain zettel”.

The second way is to present the zettel as it was recognized by Zettelstore. This is called “parsed zettel”, also retrieved with the endpoint /z/{ID}, but with the additional query parameter parseonly. Such a zettel was read and analyzed. It can be presented in various encodings.²

However, a zettel such as this one you are currently reading, is a “evaluated zettel”, also retrieved with the endpoint /z/{ID} and specifying an encoding. The biggest difference to a parsed zettel is the inclusion of block transclusions or inline transclusions for an evaluated zettel. It can also be presented in various encoding, including the “zmk” encoding. Evaluations also applies to metadata of a zettel, if appropriate.

Please note, that searching for content is based on parsed zettel. Transcluded content will only be found in transcluded zettel, but not in the zettel that transcluded the content. However, you will easily pick up that zettel by follow the backward metadata key of the transcluded zettel.

1. This is not a real problem, since every modern software should support UTF-8 as an encoding. ↩︎
2. The zmk encoding allows you to compare the plain, the parsed, and the evaluated form of a zettel. ↩︎