> :warning: This plugin will setup and start the LSP server for you, do *not* call `require("lspconfig").zk.setup()`.
#### Default configuration
**Default configuration**
```lua
require("zk").setup({
-- create user commands such as :ZkNew
create_user_commands = true,
lsp = {
-- automatically attach buffers in a zk notebook that match the given filetypes
auto_attach = {
enabled = true,
filetypes = { "markdown" },
},
-- `config` is passed to `vim.lsp.start_client(config)`
config = {
cmd = { "zk", "lsp" },
@ -53,24 +48,98 @@ require("zk").setup({
-- 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
```vim
" 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>]
```
or via Lua
where `options` can be any valid *Lua* expression that evaluates to a table.
By default, this plugin will use the path of the current buffer to determine the location of your notebook.
Note that if the current buffer does not belong to a notebook, `$ZK_NOTEBOOK_DIR` will be used to locate your notebook.
If you want, you can also explicitly specify a notebook by providing the path to any file or folder within the notebook like so `:Telescope zk notes path=/foo/bar` or so `require('telescope').extensions.zk.notes({ path = '/foo/bar'})`.
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](#notebook-directory-discovery).
You can even pass the same additional options to the Telescope pickers as described in [list and tag list commands](#commands).
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](#commands) instead.
## API
The difference between e.g. `require("zk").api.new` and `require("zk").new` is that the former lets you handle the API results yourself for more flexibility.
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.
vim.cmd("command! -nargs=? ZkNew lua require('zk').new(nil, { dir = [=[<args>]=]})")
vim.cmd("command! -nargs=? ZkNew lua require('zk').new(nil, { dir = <q-args> })")-- the command arg (directory) is interpreted relative to the notebook root
-- vim.cmd("command! -nargs=? -complete=dir ZkNew lua require('zk').new(nil, { dir = vim.fn.fnamemodify(<q-args>, ':p') })") -- this would interpret the command arg (dir) relative to the cwd instead
Karim Abou Zeid
2 years ago
committed by
GitHub