Getting started with zk

A short introduction showing how to use zk.

Create a new notebook

Create a notebook to host your notes. You are free to organize your notebook as you want, adding subdirectories if needed.

$ zk init my-notes
Initialized a notebook in my-notes

$ cd my-notes

Create your first notes

Now you are ready to write your very first note. Pick a subject, create a new note and write on!

$ zk new --title "An interesting concept"

You can customize your experience using custom templates to generate many kind of notes.

If you are not sure whether a note already exists for a particular subject, the “search or create” mode might be more appropriate than zk new. It is inspired by Notational Velocity and enables searching for an existing note or creating a new one in a single action.

From zk’s interactive edit screen, press Ctrl-E to create a new note using the current search query as title.

List existing notes

After some time, hopefully you will have enough notes to be lost in it.

To help structure your notebook, you can add metadata (e.g. keywords/tags) to your notes. You can then use zk’s powerful filtering capabilities to find the notes you need.

$ zk list --tag "recipe" --match "pizza -pineapple"

Sort the results however you need with --sort.

--format and --delimiter offer some versatile formatting options to customize the output.

zk is aware of the links you set between your notes. Backlinks or outbound links of a note can be revealed by using the link filtering options. It even supports listing indirect links thanks to --recursive.

zk supports an interactive mode powered by fzf to further filter notes manually.

Edit existing notes

To edit notes with your default editor, use zk edit. It supports the same filtering options as zk list.

$ zk edit --interactive --match "recipe pizza -pineapple"

# or with short flags
$ zk edit -i -m "recipe pizza -pineapple"

Edit the configuration file

To customize your experience with zk, you may want to edit the user configuration file.

$ vim .zk/config.toml

Declaring your own aliases is a great way to make your experience with zk easier and more familiar.