zk

https://github.com/zk-org/zk
Admin
zk is a command-line tool that helps you maintain a plain text Zettelkasten or personal wiki,...
Tokens:38,978
Snippets:424
Trust Score:5.6
License:GPL-3.0
Update:3 days ago
Show doc for...
Tokens:
Raw
### Complete LSP configuration example

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-lsp.md

A comprehensive example showing both [lsp.diagnostics] and [lsp.completion] settings configured together.

```toml
[lsp]

[lsp.diagnostics]
# Report titles of wiki-links as hints.
wiki-title = "hint"
# Warn for dead links between notes.
dead-link = "error"
# Warn when a note links to itself.
self-link = "warning"
# Report if backlinks are missing (shown at end of file).
missing-backlink = { level = "hint", position = "bottom" }

[lsp.completion]
# Show the note title in the completion pop-up, or fallback on its path if empty.
note-label = "{{title-or-path}}"
# Only suggest notes matching the given filtering options.
note-filter = "--tag project --sort modified-"
# Filter out the completion pop-up using the note title or its path.
note-filter-text = "{{title}} {{path}}"
# Show the note filename without extension as detail.
note-detail = "{{filename-stem}}"
```

--------------------------------

### Install zk via Homebrew

Source: https://github.com/zk-org/zk/blob/main/README.md

Standard installation command for Homebrew.

```sh
brew install zk
```

--------------------------------

### Install documentation requirements

Source: https://github.com/zk-org/zk/blob/main/CONTRIBUTING.md

Run this command from the repository root to install the necessary dependencies for the documentation framework.

```sh
pip install -r docs/requirements.txt
```

--------------------------------

### Complete zk configuration file example

Source: https://github.com/zk-org/zk/blob/main/docs/config/config.md

A comprehensive example of a .zk/config.toml file demonstrating various configuration sections including notebook settings, note creation rules, external tool definitions, and command aliases.

```toml
# NOTEBOOK SETTINGS
[notebook]
dir = "~/notebook"

# NOTE SETTINGS
[note]

# Language used when writing notes.
# This is used to generate slugs or with date formats.
language = "en"

# The default title used for new note, if no `--title` flag is provided.
default-title = "Untitled"

# Template used to generate a note's filename, without extension.
filename = "{{id}}-{{slug title}}"

# The file extension used for the notes.
extension = "md"

# Template used to generate a note's content.
# If not an absolute path, it is relative to .zk/templates/
template = "default.md"

# Configure random ID generation.

# The charset used for random IDs.
id-charset = "alphanum"

# Length of the generated IDs.
id-length = 4

# Letter case for the random IDs.
id-case = "lower"


# EXTRA VARIABLES
[extra]
author = "Mickaël"


# GROUP OVERRIDES
[group.journal]
paths = ["journal/weekly", "journal/daily"]

[group.journal.note]
filename = "{{format-date now}}"


# MARKDOWN SETTINGS
[format.markdown]
# Enable support for #hashtags
hashtags = true
# Enable support for :colon:separated:tags:
colon-tags = true

#[format.markdown.frontmatter]
# Define custom keys and properties of the frontmatter block
#creation-date-key = "created" # default is "date"
#modification-date-key = "changed" # default is "modified"

# EXTERNAL TOOLS
[tool]

# Default editor used to open notes.
editor = "nvim"

# Default shell used by aliases and commands.
shell = "/bin/bash"

# Pager used to scroll through long output.
pager = "less -FIRX"

# Command used to preview a note during interactive fzf mode.
fzf-preview = "bat -p --color always {-1}"

# NAMED FILTERS
[filter]
recents = "--sort created- --created-after 'last two weeks'"

# COMMAND ALIASES
[alias]

# Edit the last modified note.
edlast = "zk edit --limit 1 --sort modified- $@"

# Edit the notes selected interactively among the notes created the last two weeks.
recent = "zk edit --sort created- --created-after 'last two weeks' --interactive"

# Show a random note.
lucky = "zk list --quiet --format full --sort random --limit 1"

# LSP (EDITOR INTEGRATION)
[lsp]

[lsp.diagnostics]
# Report titles of wiki-links as hints.
wiki-title = "hint"
# Warn for dead links between notes.
dead-link = "error"
# Warn when notes link here without backlinks.
missing-backlink = { level = "warning", position = "bottom" }
```

--------------------------------

### Install zk with Nix

Source: https://github.com/zk-org/zk/blob/main/docs/index.rst

Run zk directly from the Nix store or install it permanently using nix-env.

```sh
# Run zk from Nix store without installing it:
nix run nixpkgs#zk

# Or, to install it permanently:
nix-env -iA zk
```

--------------------------------

### Install zk on Alpine Linux

Source: https://github.com/zk-org/zk/blob/main/README.md

Install zk from the testing repositories.

```sh
apk add zk
```

--------------------------------

### Install zk via MacPorts

Source: https://github.com/zk-org/zk/blob/main/README.md

Install zk using the port command.

```sh
sudo port install zk
```

--------------------------------

### Install zk on Arch Linux

Source: https://github.com/zk-org/zk/blob/main/README.md

Install zk using the pacman package manager.

```sh
sudo pacman -S zk
```

--------------------------------

### Install latest zk via Homebrew

Source: https://github.com/zk-org/zk/blob/main/README.md

Command to install the latest state of the main branch using Homebrew.

```sh
brew install --HEAD zk
```

--------------------------------

### shell helper examples

Source: https://github.com/zk-org/zk/blob/main/docs/notes/template.md

The {{sh}} helper calls a shell command and inserts its output into the template. Examples show fetching calendar events, random quotes, and weather.

```default
Get today's events from your calendar:
{{sh "icalBuddy -b '* ' -nc eventsToday"}}

Insert a random quote:
{{prepend '> ' (sh 'fortune')}}

Download today's weather:
{{sh 'curl http://wttr.in/?0'}}
```

--------------------------------

### Full-text search (fts) examples

Source: https://github.com/zk-org/zk/blob/main/docs/notes/note-filtering.md

Examples of using the default fts strategy to search for terms.

```sh
# FTS is the default match strategy
$ zk list --match "tesla OR edison"

# ...but you can enable it explicitly.
$ zk list --match-strategy fts --match "tesla OR edison"
$ zk list -Mf -m "tesla OR edison"
```

--------------------------------

### shell helper block example

Source: https://github.com/zk-org/zk/blob/main/docs/notes/template.md

When used as a block helper, the block content is passed to the command through a standard input pipe. The example outputs 'HELLO, WORLD!'.

```default
Will output "HELLO, WORLD!":
{{#sh "tr '[a-z]' '[A-Z]'"}}
Hello, world!
{{/sh}}
```

--------------------------------

### Run zk with Nix

Source: https://github.com/zk-org/zk/blob/main/README.md

Run zk without permanent installation using nix run.

```sh
nix run nixpkgs#zk
```

--------------------------------

### Configure init.lua for Neovim built-in LSP

Source: https://github.com/zk-org/zk/blob/main/docs/tips/editors-integration.md

Setup for the Neovim built-in LSP client using nvim-lspconfig to run the zk language server.

```lua
local lspconfig = require('lspconfig')
local configs = require('lspconfig/configs')

configs.zk = {
  default_config = {
    cmd = {'zk', 'lsp'},
    filetypes = {'markdown'},
    root_dir = function()
      return vim.loop.cwd()
    end,
    settings = {}
  };
}

lspconfig.zk.setup({ on_attach = function(client, buffer)
  -- Add keybindings here, see https://github.com/neovim/nvim-lspconfig#keybindings-and-completion
end })
```

--------------------------------

### style helper examples

Source: https://github.com/zk-org/zk/blob/main/docs/notes/template.md

The {{style}} helper is mostly useful when formatting content for the command-line. See the styling rules for more information.

```default
{{style 'red bold' 'A text'}}

{{#style 'underline'}}Another text{{/style}}
```

--------------------------------

### Install zk on NixOS

Source: https://github.com/zk-org/zk/blob/main/README.md

Add zk to system packages in the NixOS configuration file.

```nix
environment.systemPackages = [
  # Your other packages here
  nixpkgs.zk
];
```

--------------------------------

### Example frontmatter with changed key

Source: https://github.com/zk-org/zk/blob/main/docs/tips/modification-date.md

Include the configured key in your Markdown note frontmatter with a date value.

```markdown
---
changed: 2025-12-29 09:48
---
```

--------------------------------

### format-link helper example

Source: https://github.com/zk-org/zk/blob/main/docs/notes/template.md

Renders an internal link to another note according to user preferences. The second parameter 'title' is optional. Output depends on the note formats configuration.

```default
{{format-link "path/to note.md" "An interesting note"}}

can generate (depending on the user config):

[An interesting note](path/to%20note.md)
[[path/to note]]
```

--------------------------------

### YAML frontmatter example

Source: https://github.com/zk-org/zk/blob/main/docs/notes/note-frontmatter.md

A standard YAML header used at the top of a note to define metadata.

```yaml
---
title: Improve the structure of essays by rewriting
date: 2011-05-16 09:58:57
keywords: [writing, essay, practice]
---
```

--------------------------------

### Usage example for the wc alias

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-alias.md

Shows the output of the 'wc' alias, listing notes with their word counts sorted in ascending order.

```sh
$ zk wc
4       Integration with fzf
5       Searching and filtering notes
63      Setting your default editor
86      Anatomy of a notebook
...
```

--------------------------------

### List recent notes command

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-filter.md

Example of a command to list recent notes using multiple filtering options.

```sh
$ zk list --sort created- --created-after "last two weeks"
```

--------------------------------

### Note using custom date keys

Source: https://github.com/zk-org/zk/blob/main/docs/notes/note-frontmatter.md

An example of a markdown note utilizing the custom 'created' and 'changed' keys defined in the configuration.

```markdown
---
title: higher complexity does not always result in more order
created: 2025-12-28 09:22
changed: 2025-12-29 10:28
id: u6nh
tags: []
aliases:
---
```

--------------------------------

### Use ZK_NOTEBOOK_DIR in an alias

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-alias.md

Example of using the ZK_NOTEBOOK_DIR environment variable to create a journal entry in the notebook directory.

```toml
journal = 'zk new "$ZK_NOTEBOOK_DIR/journal"'
```

--------------------------------

### prepend helper examples

Source: https://github.com/zk-org/zk/blob/main/docs/notes/template.md

The {{prepend}} helper adds a prefix to every line of the given text or block. Can be used to generate a Markdown quote.

```default
{{prepend "> " "A quote"}}

{{#prepend "> "}}
A multiline
quote.
{{/prepend}}
```

--------------------------------

### Override default fzf options with fzf-options

Source: https://github.com/zk-org/zk/blob/main/docs/config/tool-fzf.md

Sets custom fzf options, overriding all default options used by zk. The example sets height to 40% and enables border. You may want to keep some default options like --tiebreak begin, --exact, --tabstop 4, --height 100%, --layout reverse, --no-hscroll, --color hl:-1,hl+:-1, and --preview-window wrap.

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

--------------------------------

### date helper examples

Source: https://github.com/zk-org/zk/blob/main/docs/notes/template.md

The {{date}} helper creates a date object from a natural human date string. It is most useful when paired with the {{format-date}} helper.

```default
{{date "tomorrow"}}

{{format-date (date "last week") "timestamp"}}
```

--------------------------------

### Examples of using the inline alias

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-alias.md

Two shell commands showing how to use the 'inline' alias within a 'zk list' command. The first lists notes that are not orphans, and the second lists notes linked by at least one note from the journal/ directory.

```sh
# List the notes which have at least one link pointing to them (i.e. not orphans).
$ zk list --exclude "`zk inline --orphan`"

# List the notes which are linked by at least one note from the journal/ directory.
$ zk list --linked-by "`zk inline journal`"
```

--------------------------------

### Example release commit and tag message

Source: https://github.com/zk-org/zk/blob/main/CONTRIBUTING.md

The required format for commit and tag messages when releasing a new version, including the version number and changelog entries.

```text
Release v0.15.5

Added:

- List, edit and filter for broken links with `--broken-links` (by
  @WhyNotHugo, 708)
- Update strftime package, supporting `%g` and `%G` formats in the
  `{{format-date}}` helper (by @tjex, 723)
- Option to append links to selected text, instead of replacing (by @tjex, 724)

Fixed:

- Paths with `~` and env variables no longer error when passed to
  `--notebook-dir` and `--working-dir` (by @tjex, 732)
- Guard LSP against unnecessary erroring on missing textDocument/definition
  capabilities (by @SAY-5, 718)
```

--------------------------------

### Build documentation locally

Source: https://github.com/zk-org/zk/blob/main/CONTRIBUTING.md

Use the make command to generate the static HTML site in the docs-build folder for local previewing.

```sh
make zkdocs
```

--------------------------------

### Initialize a notebook with zk init

Source: https://github.com/zk-org/zk/blob/main/docs/tips/getting-started.md

Initializes a new notebook in the specified directory. The output confirms the notebook was created. Then changes into the notebook directory.

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

$ cd my-notes
```

--------------------------------

### Build zk from source

Source: https://github.com/zk-org/zk/blob/main/README.md

Clone the repository and build the project using make.

```sh
git clone https://github.com/zk-org/zk.git
cd zk
make build
```

--------------------------------

### Build the project with make

Source: https://github.com/zk-org/zk/blob/main/CONTRIBUTING.md

Use the Makefile to compile the project, which handles necessary build parameters.

```shell
make build
```

--------------------------------

### Configure init.vim for Vim and Neovim

Source: https://github.com/zk-org/zk/blob/main/docs/tips/editors-integration.md

Custom commands and keybindings for interacting with zk via coc.nvim, including indexing and creating new notes.

```viml
" User command to index the current notebook.
"
" zk.index expects a notebook path as first argument, so we provide the current
" buffer path with expand("%:p").
command! -nargs=0 ZkIndex :call CocAction("runCommand", "zk.index", expand("%:p"))
nnoremap <leader>zi :ZkIndex<CR>

" User command to create and open a new note, to be called like this:
" :ZkNew {"title": "An interesting subject", "dir": "inbox", ...}
"
" Note the concatenation with the "edit" command to open the note right away.
command! -nargs=? ZkNew :exec "edit ".CocAction("runCommand", "zk.new", expand("%:p"), <args>).path

" Create a new note after prompting for its title.
nnoremap <leader>zn :ZkNew {"title": input("Title: ")}<CR>
" Create a new note in the directory journal/daily.
nnoremap <leader>zj :ZkNew {"dir": "journal/daily"}<CR>
```

--------------------------------

### Configure zk with Home Manager

Source: https://github.com/zk-org/zk/blob/main/README.md

Enable and configure zk using the Home Manager module.

```nix
programs.zk.enable = true;

# Modify `${XDG_CONFIG_HOME}/zk/config.toml` through this attr
programs.zk.settings = {
  # Add your own configuration settings for zk here
};
```

--------------------------------

### Apply inline and block styles with {{style}}

Source: https://github.com/zk-org/zk/blob/main/docs/tips/style.md

Demonstrates both inline styling for single lines and block styling for multi-line content using the {{style}} helper.

```default
Inline: {{style "red bold" "One is never alone with a rubber duck."}}

Block:
{{#style "underline"}}
For a moment, nothing happened. Then, after a second
or so, nothing continued to happen.
{{/style}}
```

--------------------------------

### Create a note from file content

Source: https://github.com/zk-org/zk/blob/main/docs/notes/note-creation.md

Redirect a file into zk new --interactive to use its contents as the initial note template.

```bash
$ zk new --interactive < file.txt
```

--------------------------------

### Configure missing-backlink diagnostic

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-lsp.md

Example of setting the missing-backlink diagnostic level and position within the [lsp.diagnostics] section.

```toml
[lsp.diagnostics]
missing-backlink = { level = "warning", position = "bottom" }
```

--------------------------------

### Use recents named filter with edit command

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-filter.md

Example of using the 'recents' named filter with the edit command.

```sh
$ zk edit recents --interactive
```

--------------------------------

### Verify zk build

Source: https://github.com/zk-org/zk/blob/main/README.md

Run make and check the help output on macOS or Linux.

```sh
$ make
$ ./zk -h
```

--------------------------------

### Use recents named filter with limit

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-filter.md

Example of using the 'recents' named filter with an additional limit option.

```sh
$ zk list recents --limit 10
```

--------------------------------

### Execute unit tests

Source: https://github.com/zk-org/zk/blob/main/CONTRIBUTING.md

Run unit tests using the standard Go testing library.

```shell
make test
```

--------------------------------

### Override native command options with an alias

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-alias.md

Example of overriding the default edit command by wrapping it with additional flags.

```toml
[alias]
edit = 'zk edit --interactive "$@"'
```

--------------------------------

### Create a note from clipboard content

Source: https://github.com/zk-org/zk/blob/main/docs/notes/note-creation.md

Pipe the output of pbpaste into zk new --interactive to use the macOS clipboard as the initial content for a new note.

```bash
$ pbpaste | zk new --interactive
```

--------------------------------

### Configure a custom alias for search strategy

Source: https://github.com/zk-org/zk/blob/main/docs/notes/note-filtering.md

Example of setting a default search strategy using a custom alias in the TOML configuration.

```toml
[alias]
list = "zk list --match-strategy re $@"
```

--------------------------------

### zk.new

Source: https://github.com/zk-org/zk/blob/main/docs/tips/editors-integration.md

Creates a new note in the notebook. Takes a path to locate the notebook and optional options, and returns the path and content of the created note.

```APIDOC
## zk.new

### Description
Creates a new note in the notebook.

### Arguments
1. **path** (string) - Required - A path to any file or directory in the notebook, to locate it.
2. **options** (dictionary) - Optional - Additional options.

#### Options
- **title** (string) - Optional - Title of the new note.
- **content** (string) - Optional - Initial content of the note.
- **dir** (string) - Optional - Parent directory, relative to the root of the notebook.
- **group** (string) - Optional - Note configuration group.
- **template** (string) - Optional - Custom template used to render the note.
- **extra** (dictionary) - Optional - A dictionary of extra variables to expand in the template.
- **date** (string) - Optional - A date of creation for the note in natural language, e.g. "tomorrow".
- **edit** (boolean) - Optional - When true, the editor will open the newly created note (not supported by all editors).
- **dryRun** (boolean) - Optional - When true, zk will not actually create the note on the file system, but will return its generated content and path.
- **append** (boolean) - Optional - Append the link to selection instead of replacing it.
- **insertLinkAtLocation** (location) - Optional - A location in another note where a link to the new note will be inserted.
- **insertContentAtLocation** (location) - Optional - A location in another note where the content of the new note will be inserted.

### Returns
A dictionary with two properties:
- **path** (string) - The absolute path to the created note.
- **content** (string) - The raw content of the created note.
```

--------------------------------

### List configured aliases

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-alias.md

Command to display all aliases currently defined in the configuration file.

```bash
zk config --list aliases
```

--------------------------------

### Configure Neuron ID format

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-note.md

Example configuration for the [note] section to match the Neuron ID format using hex characters with a length of 8 in lowercase.

```toml
[note]
id-charset = "hex"
id-length = 8
id-case = "lower"
```

--------------------------------

### Build development version of zk

Source: https://github.com/zk-org/zk/blob/main/README.md

Switch to the dev branch and build the project.

```sh
git checkout dev
make build
```

--------------------------------

### List configured extra variables

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-extra.md

Use the zk config --list extras command to display all extra variables defined in the configuration file.

```sh
zk config --list extras
```

--------------------------------

### Customize Ctrl-E key binding with fzf-bind-new

Source: https://github.com/zk-org/zk/blob/main/docs/config/tool-fzf.md

Changes the key binding for creating a new note during interactive filtering. The example sets it to Ctrl-C. Setting it to an empty string disables the binding.

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

--------------------------------

### Create a new note with zk new

Source: https://github.com/zk-org/zk/blob/main/docs/tips/getting-started.md

Creates a new note with the given title. Use --title to specify the note title.

```sh
$ zk new --title "An interesting concept"
```

--------------------------------

### Filter notes by tags with zk list --tag

Source: https://github.com/zk-org/zk/blob/main/docs/notes/tags.md

Use the --tag option with zk list to filter notes by tags. The example shows a query combining 'inbox OR todo' and excluding 'done'.

```sh
$ zk list --tag "inbox OR todo, NOT done"
```

--------------------------------

### Create ephemeral shell with zk

Source: https://github.com/zk-org/zk/blob/main/README.md

Create a temporary shell environment with zk available.

```sh
nix shell nixpkgs#zk
```

--------------------------------

### Create a note from a free title

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-alias.md

The 'nt' alias creates a new note with a title passed as a single argument. Using '"$*"' allows the title to be passed without quoting, as shown in the usage example.

```toml
nt = 'zk new --title "$*"'
```

--------------------------------

### Custom Markdown link template in TOML

Source: https://github.com/zk-org/zk/blob/main/docs/notes/note-format.md

Example configuration for the [format.markdown] section that sets link-format to a custom template generating wiki links using frontmatter ID and title. The template uses variables like {{metadata.id}} and {{title}}.

```toml
[format.markdown]
link-format = "[[{{metadata.id}}|{{title}}]]"
```

--------------------------------

### List configured filters

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-filter.md

Command to display all filters defined in the configuration file.

```sh
$ zk config --list filters
```

--------------------------------

### Configure notebook directory in config.toml

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-notebook.md

Sets the default notebook directory using the [notebook] section. The path supports tilde expansion for the user home directory and environment variables.

```toml
[notebook]
dir = "~/notebook" # same as "$HOME/notebook"
```

--------------------------------

### Create a note and save its path into the clipboard (macOS)

Source: https://github.com/zk-org/zk/blob/main/docs/config/config-alias.md

The 'ntc' alias builds on the 'nt' alias but copies the created note's path to the macOS clipboard using 'pbcopy' instead of editing it.

```toml
ntc = 'zk new --print-path --title "$*" | pbcopy'
```

--------------------------------

### Edit the configuration file with vim

Source: https://github.com/zk-org/zk/blob/main/docs/tips/getting-started.md

Opens the user configuration file in vim for customization.

```sh
$ vim .zk/config.toml
```

--------------------------------

### Set fzf-preview to use bat for syntax highlighting

Source: https://github.com/zk-org/zk/blob/main/docs/config/tool-fzf.md

Customizes the fzf preview command to use bat with syntax highlighting. The placeholder {-1} is expanded to the note file path. This overrides the default cat preview.

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

--------------------------------

### Set fzf-preview to use nested zk list for metadata preview

Source: https://github.com/zk-org/zk/blob/main/docs/config/tool-fzf.md

Customizes the fzf preview command to show more metadata by running a nested zk list command. The placeholder {-1} is expanded to the note file path.

```toml
[tool]
fzf-preview = "zk list --quiet --format full --limit 1 {-1}"
```
Tokens:
Raw