Zettelmarkup: Zettel Transclusion

A zettel transclusion is specified by the following sequence, starting at the first position in a line: {{{zettel-identifier}}}.

When evaluated, the referenced zettel is read. If it contains some transclusions itself, these will be expanded, recursively. When a recursion is detected, expansion does not take place. Instead an error message replaces the transclude specification.

An error message is also given, if the zettel cannot be read or if too many transclusions are made. The maximum number of transclusion can be controlled by setting the value max-transclusions of the runtime configuration zettel.

If everything went well, the referenced, expanded zettel will replace the transclusion element.

For example, to include the text of the Zettel titled “Zettel identifier”, just specify its identifier 00001006050000 in the transclude element:

{{{00001006050000}}}

This will result in:

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

Timestamp-based identifier

Every zettel identifier consists of 14 digits. They resemble a timestamp: the first four digits could represent the year, the next two represent the month, following by day, hour, minute, and second.1

This allows to order zettel chronologically in a canonical way.

In most cases the zettel identifier is the timestamp when the zettel was created.

However, the Zettelstore software just checks for exactly 14 digits. Anybody is free to assign a “non-timestamp” identifier to a zettel, e.g. with a month part of “35” or with “99” as the last two digits.

Some zettel identifier are reserved and should not be used otherwise. All identifiers of zettel initially provided by an empty Zettelstore begin with “000000”, except the home zettel 00010000000000. Zettel identifier of this manual have be chosen to begin with “000010”.

A zettel can have any identifier that contains 14 digits and that is not in use by another zettel managed by the same Zettelstore.

Identifiers with four alphanumeric characters

In the future, above identifier format will change. The migration to the new format starts with Zettelstore version 0.18 and will last approximately until version 0.22.

Above described format of 14 digits will be changed to four alphanumeric characters, i.e. the digits 0 to 9, and the letters a to z. You might note that using 14 digits you are allowed a little less than 1014 Zettel, i.e. more than 999 trillion zettel, while the new scheme only allows you to create 364-1 zettel (1679615 zettel, to be exact). Since Zettelstore is a single-user system, more than a million zettel should be enough. However, there must be a way to replace an identifier with 14 digits by an identifier with four characters.

As a first step, the list of reserved zettel identifier is updated, as well as ways of client software to use predefined identifier.

Please note: if the referenced zettel is changed, all transclusions will also change.

This allows, for example, to create a bigger document just by transcluding smaller zettel.

In addition, if a zettel z transcludes a zettel t, but the current user is not allowed to view zettel t (but zettel z), then the transclusion will not take place. To the current user, it seems that there was no transclusion in zettel z. This allows to create a zettel with content that seems to be changed, depending on the authorization of the current user.


Any attributes added to the transclusion will set/overwrite the appropriate metadata of the included zettel. Of course, this applies only to thoes attribtues, which have a valid name for a metadata key. This allows to control the evaluation of the included zettel, especially for zettel containing a diagram description.

See also

Inline-mode transclusion does not work at the paragraph / block level, but is used for inline-structured elements.

  1. Zettel identifier format will be migrated to a new format after version 0.19, without reference to the creation date. ↩︎