Integration with fzf

fzf is an awesome and versatile fuzzy finder powering zk’s interactive filtering mode.

Besides the standard fzf configuration options documented on its website, zk offers additional options you can set in the [tool] configuration section.

If you wish to customize more of fzf behavior, please post a feature request.

Preview command

You can customize the command used to preview a note with fzf-preview. The special placeholder {-1} will be expanded to the note file path.

By default, zk uses cat for preview, which is a bit boring. A much better option would be to use bat which supports syntax highlighting.

[tool]
fzf-preview = "bat -p --color always {-1}"

Or, if you prefer to preview more metadata, you can use a nested zk command.

[tool]
fzf-preview = "zk list --quiet --format full --limit 1 {-1}"

Line format

With the fzf-line setting property, you can provide your own template to customize the format of each fzf line. The lines are used by fzf for the fuzzy matching, so if you want to search in the full note content, do not forget to add {{body}} in your custom template.

The default line template is {{style "title" title-or-path}} {{style "understate" body}} {{style "understate" (json metadata)}}.

Here’s an example using different colors and showing the list of tags as #hashtags:

[tool]
fzf-line = "{{style 'blue' rel-path}}{{#each tags}} #{{this}}{{/each}} {{style 'black' body}}"

Template context

The following variables are available in the line template.

Variable

Type

Description

filename

string

Filename of the note, including its extension

filename-stem

string

Filename of the note without the file extension

path

string

File path to the note, relative to the notebook root

abs-path

string

Absolute file path to the note

rel-path

string

File path to the note, relative to the current directory

title

string

Note title

title-or-path

string

Note title or path if empty

body

string

All of the note content, minus the heading

raw-content

string

The full raw content of the note file

word-count

int

Number of words in the note

tags

[string]

List of tags found in the note

metadata

map

YAML frontmatter metadata, e.g. metadata.description1

created

date

Date of creation of the note

modified

date

Last date of modification of the note

checksum

string

SHA-256 checksum of the note file

  1. YAML keys are normalized to lower case.

fzf options

You can override the default fzf options used by zk with fzf-options. Look at man fzf for the list of available options.

[tool]
fzf-options = "--height 40% --border"

Note that this overrides all the default options used by zk, you might want to keep some of them:

  • --tiebreak begin Prefer matches located at the beginning of the line

  • --exact Look for exact matches instead of fuzzy ones by default

  • --tabstop 4 Length of tab characters

  • --height 100% Height of the list relative to the terminal window

  • --layout reverse Display the input field at the top

  • --no-hscroll Make sure the path and titles are always visible

  • --color hl:-1,hl+:-1 Don’t highlight search terms

  • --preview-window wrap Enable line wrapping in the preview window

Key bindings

When running fzf with zk edit --interactive, you can create a new note with the Ctrl-E key binding. This binding is customizable with fzf-bind-new. You can also disable it by setting it to an empty string ("").

[tool]
fzf-bind-new = "Ctrl-C"