zk

Stupid-fast plain-text Zettelkasten (zk) built for (terminal) nerds. Heavily featuring fzf, ripgrep, bat, and sqlite.

The goal of the zk repository is to collect scripts and configurations for other plain-text Zettelkasten users.

Note: This is an on-going extraction from my local environment, but has the utilities I use by far the most often. I can almost guarantee you you're going to run into a stacktrace somewhere because of some utility that isn't installed, etc. Please open issues if it's not working, or you have questions, concerns, comments. I'd also love contributions of scripts to bin/, such as showing related notes, polish to search, Vim configs, etc.

In this screenshot, we have zks running in the top-right, zkt in the bottom-right, and vim in the left pane. zk can be used without tmux, but it's recommended to use tmux.

Usage

The scripts assumes $ZK_PATH is set to your Zettelkasten directory. Your Zettelkasten are markdown files in this directory. Nesting is presently not supported. Each note must have a 12-number prefix (date note was created), e.g. 202005050837 Monkey Ladder.md. It's recommended to do some kind of backup, e.g. Dropbox/iCloud/...

Your zk Zettelkasten is designed to be edited with your favourite editor. Currently zk only supports Vim natively. zk augments your editor with various scripts to help extract further value.

zks. fzf-enabled full-text search (top-right pane in screenshot above) over all your notes, using sqlite. The index updates automatically based on file modification. See the FZF_DEFAULT_OPTS below for various key-bindings you can use to open splits in Vim, copy to clipboard, etc. directly from here. Alt-S will find similar notes with zksim.

zksim. Finds similar notes to the note passed as an argument. See #1 for more.

zkt. fzf-enabled tag browser. Pressing enter on a tag will show you notes with that tag. notes, using sqlite. See the FZF_DEFAULT_OPTS below for various key-bindings you can use to open splits, copy to clipboard, etc. directly from here.

zkt-raw. Raw list of tags sorted by totals. Useful for other analysis. Used by zkt.

zkn. Create a new note, with an appropriate prefix.

zk-assets-localize. Given a file, downloads/copies the markdown images to media/.

Installation

Clone zk and add bin/ to your $PATH:

$ git clone https://github.com/sirupsen/zk.git ~/zk
$ echo 'export PATH=$PATH:$HOME/zk/bin' >> ~/.bashrc
$ echo 'export ZK_PATH="$HOME/Zettelkasten"' >> ~/.bashrc

Install the dependencies with your package manager.

MacOS:

# brew install ripgrep fzf sqlite3 bat
# gem install sqlite3

Linux:

build-essential,libsqlite3-dev and ruby-dev are needed to install the sqlite3 gem. For example—on Debian/Ubuntu, run:

# apt install ripgrep fzf sqlite3 bat build-essential libsqlite3-dev ruby ruby-dev
# gem install sqlite3

For Vim, you can use this in the config to add a :Note to add new notes with the prefix, as well as auto-completion for tags and links. Make sure to use bouk/vim-markdown to get proper highlighting for links.

If you're using fzf with vim, it's recommended to add this to your bash configuration. It adds super useful key-bindings to open files from zkt and zks:

export FZF_DEFAULT_OPTS="--height=40% --multi --tiebreak=begin \
  --bind 'ctrl-y:execute-silent(echo {} | pbcopy)' \
  --bind 'alt-down:preview-down,alt-up:preview-up' \
  --bind \"ctrl-v:execute-silent[ \
    tmux send-keys -t \{left\} Escape :vs Space && \
    tmux send-keys -t \{left\} -l {} && \
    tmux send-keys -t \{left\} Enter \
  ]\"
  --bind \"ctrl-x:execute-silent[ \
    tmux send-keys -t \{left\} Escape :sp Space && \
    tmux send-keys -t \{left\} -l {} && \
    tmux send-keys -t \{left\} Enter \
  ]\"
  --bind \"ctrl-o:execute-silent[ \
    tmux send-keys -t \{left\} Escape :read Space ! Space echo Space && \
    tmux send-keys -t \{left\} -l \\\"{}\\\" && \
    tmux send-keys -t \{left\} Enter \
  ]\""