zk-nvim/README.md

zk-nvim

Neovim extension for zk.

Install

Using packer.nvim

use {
  "mickael-menu/zk-nvim",
  requires = { "neovim/nvim-lspconfig" }
}

-- Telescope is optional
use {
  'nvim-telescope/telescope.nvim',
  requires = { {'nvim-lua/plenary.nvim'} }
}

Using vim-plug

Plug "mickael-menu/zk-nvim"
Plug "neovim/nvim-lspconfig"

Plug 'nvim-telescope/telescope.nvim' " optional
Plug 'nvim-lua/plenary.nvim' " optional, dependency for Telescope

Setup

require("zk").setup()
require("telescope").load_extension("zk")

⚠️ This plugin will setup and start the LSP server for you, do not call require("lspconfig").zk.setup().

Default configuration

require("zk").setup({
  -- create user commands such as :ZkNew
  create_user_commands = true,

  lsp = {
    -- `config` is passed to `vim.lsp.start_client(config)`
    config = {
      cmd = { "zk", "lsp" },
      name = "zk",
      -- init_options = ...
      -- on_attach = ...
      -- etc, see `:h vim.lsp.start_client()`
    },

    -- automatically attach buffers in a zk notebook that match the given filetypes
    auto_attach = {
      enabled = true,
      filetypes = { "markdown" },
    },
  },
})

Notebook Directory Discovery

When you run a notebook command, this plugin will look for a notebook in the following places and order:

1. the current buffer path (i.e. the file you are currently editing),
2. the current working directory,
3. the $ZK_NOTEBOOK_DIR environment variable.

We recommend you to export the $ZK_NOTEBOOK_DIR environment variable, so that a notebook can always be found.

It is worth noting that for some notebook commands you can explicitly specify a notebook by providing a path to any file or directory within the notebook. An explicitly provided path will always take precedence and override the automatic notebook discovery. However, this is always optional, and usually not necessary.

Commands

VimL

" Indexes the notebook
:ZkIndex

" Creates and opens a new note
" params
"   (optional) directory for the new note, relative to the notebook root
:ZkNew [<directory>]

" Opens a Telescope picker
" params
"   (optional) additional options, see https://github.com/mickael-menu/zk/blob/main/docs/editors-integration.md#zklist
:ZkList [<options>]

" Opens a Telescope picker
" params
"   (optional) additional options, see https://github.com/mickael-menu/zk/blob/main/docs/editors-integration.md#zktaglist
:ZkTagList [<options>]

where options can be any valid Lua expression that evaluates to a table.

Examples:

:ZkNew daily
:ZkList { createdAfter = "3 days ago", tags = { "work" } }

Lua

---Indexes the notebook
--
---@param path? string path to explicitly specify the notebook
---@param options table additional options
---@see https://github.com/mickael-menu/zk/blob/main/docs/editors-integration.md#zkindex
require("zk").index(path, options)

---Creates and opens a new note
--
---@param path? string path to explicitly specify the notebook
---@param options table additional options
---@see https://github.com/mickael-menu/zk/blob/main/docs/editors-integration.md#zknew
require("zk").new(path, options)

---Opens a Telescope picker
--
---@param path? string path to explicitly specify the notebook
---@param options table additional options
---@see https://github.com/mickael-menu/zk/blob/main/docs/editors-integration.md#zklist
require("zk").list(path, options)

---Opens a Telescope picker
--
---@param path? string path to explicitly specify the notebook
---@param options table additional options
---@see https://github.com/mickael-menu/zk/blob/main/docs/editors-integration.md#zktaglist
require("zk").tag.list(path, options)

Examples:

require("zk").new(nil, { dir = "daily" })
require("zk").list(nil, { createdAfter = "3 days ago", tags = { "work" } })

As you can see, the path is optional, and can usually be omitted; see Notebook Directory Discovery.

Telescope

:Telescope zk notes
:Telescope zk orphans
:Telescope zk backlinks
:Telescope zk links
:Telescope zk related
:Telescope zk tags

or via Lua

require('telescope').extensions.zk.notes()
require('telescope').extensions.zk.orphans()
require('telescope').extensions.zk.backlinks()
require('telescope').extensions.zk.links()
require('telescope').extensions.zk.related()
require('telescope').extensions.zk.tags()

The Telescope pickers also allow you to explicitly specify a notebook like so :Telescope zk notes path=/foo/bar or so require('telescope').extensions.zk.notes({ path = '/foo/bar'}). However, specifing a path is optional, and is usually not necessary; see Notebook Directory Discovery.

You can even pass the same additional options to the Telescope pickers as described in list and tag list commands.

Example VimL:

:Telescope zk notes createdAfter=3\ days\ ago

Example Lua:

require('telescope').extensions.zk.notes({ createdAfter = "3 days ago", tags = { "work" } })

As you can see, the VimL API is a bit constrained. Whitespace must be escaped and lists and dictionaries are not supported. It is therefore recommended to use the :ZkList and :ZkTagList commands instead.

API

The functions in the API module give you maximum flexibility and provide only a thin Lua friendly layer around zk's API. You can use it to write your own specialized functions for interacting with zk.

-- https://github.com/mickael-menu/zk/blob/main/docs/editors-integration.md#zkindex
-- path and options are optional
require("zk").api.index(path, options, function(stats)
  -- do something with the stats
end)

-- https://github.com/mickael-menu/zk/blob/main/docs/editors-integration.md#zknew
-- path and options are optional
require("zk").api.new(path, options, function(res)
  file_path = res.path
  -- do something with the new file path
end)

-- https://github.com/mickael-menu/zk/blob/main/docs/editors-integration.md#zklist
-- path is optional, options.select is required
-- options = { select = { "title", "absPath", "rawContent" }, sort = { "created" } }
require("zk").api.list(path, options, function(notes)
  -- do something with the notes
end)

-- https://github.com/mickael-menu/zk/blob/main/docs/editors-integration.md#zktaglist
-- path and options are optional
require("zk").api.tag.list(path, options, function(tags)
  -- do something with the tags
end)

Example Mappings

vim.api.nvim_set_keymap(
  "n",
  "<Leader>zn",
  "<cmd>lua require('telescope').extensions.zk.notes()<CR>",
  { noremap = true }
)

vim.api.nvim_set_keymap(
  "n",
  "<Leader>zo",
  "<cmd>lua require('telescope').extensions.zk.orphans()<CR>",
  { noremap = true }
)

vim.api.nvim_set_keymap(
  "n",
  "<Leader>zb",
  "<cmd>lua require('telescope').extensions.zk.backlinks()<CR>",
  { noremap = true }
)

vim.api.nvim_set_keymap(
  "n",
  "<Leader>zl",
  "<cmd>lua require('telescope').extensions.zk.links()<CR>",
  { noremap = true }
)

vim.api.nvim_set_keymap(
  "n",
  "<Leader>zt",
  "<cmd>lua require('telescope').extensions.zk.tags()<CR>",
  { noremap = true }
)