Tips and Tricks

Welcome Zettel

• Problem: You want to put your Zettelstore into the public and need a starting zettel for your users. In addition, you still want a “home zettel”, with all your references to internal, non-public zettel. Zettelstore only allows to specify one home-zettel.

• Solution 1:

  1. Create a new zettel with all your references to internal, non-public zettel. Let's assume this zettel receives the zettel identifier 20220803182600.
  2. Create the zettel that should serve as the starting zettel for your users. It must have syntax Zettelmarkup, i.e. the syntax metadata must be set to zmk. If needed, set the runtime configuration ''home-zettel to the value of the identifier of this zettel.
  3. At the beginning of the start zettel, add the following Zettelmarkup text in a separate paragraph: {{{20220803182600}}} (you have to adapt to the actual value of the zettel identifier for your non-public home zettel).

• Discussion: As stated in the description for a transclusion, a transclusion will be ignored, if the transcluded zettel is not visible to the current user. In effect, the transclusion statement (above paragraph that contained {{{...}}}) is ignored when rendering the zettel.

• Solution 2: Set a user-specific value by adding metadata home-zettel to the user zettel.

• Discussion: A value for home-zettel is first searched in the user zettel of the current authenticated user. Only if it is not found, the value is looked up in the runtime configuration zettel. If multiple user should use the same home zettel, its zettel identifier must be set in all relevant user zettel.

Role-specific Layout of Zettel in Web User Interface (WebUI)

• Problem: You want to add some CSS when displaying zettel of a specific role. For example, you might want to add a yellow background color for all configuration zettel. Or you want a multi-column layout.

• Solution: If you enable expert-mode, you will have access to a zettel called “Zettelstore Sxn Start Code” (its identifier is 00000000019000). This zettel is the starting point for Sxn code, where you can place a definition for a variable named “CSS-ROLE-map”.

  But first, create a zettel containing the needed CSS: give it any title, its role is preferably “configuration” (but this is not a must). Its syntax must be set to “css”. The content must contain the role-specific CSS code, for example body {background-color: #FFFFD0}for a background in a light yellow color.

  Let's assume, the newly created CSS zettel got the identifier 20220825200100.

  Now, you have to map this freshly created zettel to a role, for example “zettel”. Since you have enabled expert-mode, you are allowed to modify the zettel “Zettelstore Sxn Start Code”. Add the following code to the Sxn Start Code zettel: (set! CSS-ROLE-map '(("zettel" . "20220825200100"))).

  In general, the mapping must follow the pattern: (ROLE . ID), where ROLE is the placeholder for the role, and ID for the zettel identifier containing CSS code. For example, if you also want the role “configuration” to be rendered using that CSS, the code should be something like (set! CSS-ROLE-map '(("zettel" . "20220825200100") ("configuration" . "20220825200100"))).

• Discussion: you have to ensure that the CSS zettel is allowed to be read by the intended audience of the zettel with that given role. For example, if you made zettel with a specific role public visible, the CSS zettel must also have a visibility: public metadata.

Zettel synchronization with iCloud (Apple)

• Problem: You use Zettelstore on various macOS computers and you want to use the sameset of zettel across all computers.

• Solution: Place your zettel in an iCloud folder.

  To configure Zettelstore to use the folder, you must specify its location within you directory structure as box-uri-X (replace X with an appropriate number). Your iCloud folder is typically placed in the folder ~/Library/Mobile Documents/com~apple~CloudDocs. The “~” is a shortcut and specifies your home folder.

  Unfortunately, Zettelstore does not yet support this shortcut. Therefore you must replace it with the absolute name of your home folder. In addition, a space character is not allowed in an URI. You have to replace it with the sequence “%20”.

  Let us assume, that you stored your zettel box inside the folder “zettel”, which is located top-level in your iCloud folder. In this case, you must specify the following box URI within the startup configuration: box-uri-1: dir:///Users/USERNAME/Library/Mobile%20Documents/com~apple~CloudDocs/zettel, replacing USERNAME with the username of that specific computer (and assuming you want to use it as the first box).

• Solution 2: If you typically start your Zettelstore on the command line, you could use the -d DIR option for the run sub-command. In this case you are allowed to use the character “~”.

  zettelstore run -d ~/Library/Mobile\ Documents/com\~apple\~CloudDocs/zettel

  (The “\” is needed by the command line processor to mask the following character to be processed in unintended ways.)

• Discussion: Zettel files are synchronized between your computers via iCloud. Is does not matter, if one of your computer is offline / switched off. iCloud will synchronize the zettel files if it later comes online.

  However, if you use more than one computer simultaneously, you must be aware that synchronization takes some time. It might take several seconds, maybe longer, that new new version of a zettel appears on the other computer. If you update the same zettel on multiple computers at nearly the same time, iCloud will not be able to synchronize the different versions in a safe manner. Zettelstore is intentionally not aware of any synchronization within its zettel boxes.

  If Zettelstore behaves strangely after a synchronization took place, the page about Troubleshooting might contain some useful information.