zk-nvim

https://github.com/zk-org/zk-nvim
Admin
zk-nvim is a Neovim extension designed to integrate with and enhance the `zk` plain text note-taking...
Tokens:70,708
Snippets:480
Trust Score:5.6
License:GPL-3.0
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Advanced setup example with picker theme and LSP overrides

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/zk.md

Shows a more detailed setup with a picker theme, LSP configuration, and tag multi-select strategy. Note that the plugin starts the LSP server itself, so do not also call require("lspconfig").zk.setup().

```lua
require("zk").setup({
  picker = "telescope",
  picker_options = {
    telescope = require("telescope.themes").get_ivy(),
  },
  lsp = {
    config = {
      cmd = { "zk", "lsp" },
      on_attach = function(client, bufnr)
        -- custom LSP keymaps
      end,
    },
  },
  tags = { multi_select_strategy = "OR" },
})
```

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

### start() basic call example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/lsp.md

Calls start() and then asserts that the client is available.

```lua
require("zk.lsp").start()
assert(require("zk.lsp").client(), "zk LSP client should now be available")
```

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

### Setup zk LSP server with nvim-lsp-installer

Source: https://github.com/zk-org/zk-nvim/blob/main/doc/zk.txt

Lua setup for the zk LSP server when installed via nvim-lsp-installer. Customizes the server options and passes them to zk.setup(). The documentation notes that installing the zk CLI tool directly is recommended instead.

```lua
require("nvim-lsp-installer").on_server_ready(function(server)
  local opts = {
    -- customize your options as usual
    --
    -- on_attach = ...
    -- etc, see `:h vim.lsp.start_client()`
  }
  if server.name == "zk" then
    require("zk").setup({
      lsp = {
        config = vim.tbl_extend("force", server:get_default_options(), opts),
      },
    })
  else
    server:setup(opts)
  end
end)
```

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

### get() basic call example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/commands.md

Shows how to call built-in commands directly via get() with the appropriate arguments. The first call passes a table with dir, the second passes createdAfter and tags, and the third passes no arguments.

```lua
require("zk.commands").get("ZkNew")({ dir = "daily" })
require("zk.commands").get("ZkNotes")({ createdAfter = "3 days ago", tags = { "work" } })
require("zk.commands").get("ZkNewFromTitleSelection")()
```

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

### start() function implementation

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/lsp.md

Starts the zk LSP client if not already started. Uses an external client if available, otherwise starts a new client via vim.lsp.start with config.options.lsp.config. Caches the client id and is a no-op if a client is already known.

```lua
function M.start()
  if not client_id then
    client_id = M.external_client()
  end

  if not client_id then
    local id = vim.lsp.start(config.options.lsp.config)
    if id then
      client_id = id
    end
  end
end
```

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

### Install with lazy.nvim

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

Install zk-nvim using lazy.nvim with a table configuration.

```lua
{
  "zk-org/zk-nvim",
  name = "zk",
  opts = {
    -- See Setup section below
  },
}
```

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

### zk.lsp.start()

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/index.md

Starts the LSP client for the zk server.

```APIDOC
## zk.lsp.start()

### Description
Starts the LSP client for the zk server.

### Method
start

### Usage
```lua
require("zk.lsp").start()
```
```

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

### Telescope picker: setup and show_note_picker usage

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/pickers.md

Shows basic setup with telescope as the picker and a direct call to show_note_picker. The note shape must match the configured selection { "title", "absPath", "path" }.

```lua
require("zk").setup({ picker = "telescope" })
-- when calling show_note_picker directly, the note shape must match selection:
require("zk.pickers.telescope").show_note_picker(
  { { title = "a", absPath = "/tmp/a.md", path = "a.md" } },
  { prompt_title = "Open", multi_select = false },
  function(note) if note then vim.cmd("edit " .. note.absPath) end end
)
```

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

### Default lazy.nvim setup

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

Default lazy.nvim setup for zk-nvim, including picker and LSP configuration.

```lua
return {
  "zk-org/zk-nvim",
  name = "zk",
  opts = {
    -- Can be "telescope", "fzf", "fzf_lua", "minipick", "snacks_picker",
    -- or select" (`vim.ui.select`).
    picker = "select",

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

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

    tags = {
      -- Configure how multiple tags should be combined in a ZkTags search
      -- Can be "AND" or "OR"
      multi_select_strategy = "AND",
    }
  },
}
```

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

### zk.setup(options)

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/index.md

Initializes the plugin, merges user options into the default configuration, optionally installs autocmds for LSP auto-attach, and loads built-in commands.

```APIDOC
## zk.setup(options)

### Description
Initializes the plugin, merges user options into the default configuration, optionally installs autocmds for LSP auto-attach, and loads built-in commands.

### Method
setup

### Parameters
- **options** (table) - Optional - User configuration options to merge with defaults.

### Usage
```lua
require("zk").setup({})
```
```

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

### client() defensively vs. internal usage example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/lsp.md

Shows how to guard before calling methods that need a client, as zk.api internally uses lsp.client():request(...). The example starts the LSP client, then checks if a client exists before making a request.

```lua
local lsp = require("zk.lsp")
lsp.start()
-- zk.api internally does: lsp.client():request("workspace/executeCommand", ...)
-- so guard before calling methods that need a client
local c = lsp.client()
if c then c.request("workspace/executeCommand", { command = "zk.list", arguments = { nil, nil } }) end
```

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

### start() guarded use with external client fallback

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/lsp.md

Calls start() and then checks if an external client was used; if not, notifies that zk-nvim started its own client.

```lua
local lsp = require("zk.lsp")
lsp.start()
if not lsp.external_client() then
  vim.notify("zk-nvim started its own zk LSP client")
end
```

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

### stop() restart cycle example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/lsp.md

Shows a restart cycle: stop the LSP client, then start it fresh with config.options.lsp.config, and print the new client's id.

```lua
local lsp = require("zk.lsp")
lsp.stop()      -- tear down
lsp.start()     -- start fresh with config.options.lsp.config
print(lsp.client().id)
```

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

### setup() function definition (lua/zk.lua:40)

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/zk.md

Defines the plugin entry point. It deep-merges user options over defaults, optionally sets up LSP auto-attach, and loads built-in commands.

```lua
---The entry point of the plugin
--
---@param options? table user configuration options
function M.setup(options)
  config.options = vim.tbl_deep_extend("force", config.defaults, options or {})

  if config.options.lsp.auto_attach.enabled then
    setup_lsp_auto_attach()
  end

  require("zk.commands.builtin")
end
```

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

### get_pick_notes_list_api_selection basic call example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/ui.md

Example of using `get_pick_notes_list_api_selection` to fetch notes and pass them to `pick_notes`.

```lua
local ui = require("zk.ui")
local api = require("zk.api")
api.list(nil, { selection = ui.get_pick_notes_list_api_selection({}) }, function(err, notes)
  ui.pick_notes(notes, {}, function(sel) vim.notify(vim.inspect(sel)) end)
end)
```

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

### setup(options)

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/zk.md

The entry point of the plugin. Configures the plugin by merging user options with defaults, optionally enables LSP auto-attach, and loads built-in commands.

```APIDOC
## setup(options)

### Description
The entry point of the plugin. Configures the plugin by merging user options with defaults, optionally enables LSP auto-attach, and loads built-in commands.

### Method
setup

### Parameters
- `options` (table) - Optional - User configuration; deep-merged ("force") over `zk.config.defaults`. See [configuration.md](../configuration.md)

### Return
`nil`. Side effects: sets `zk.config.options`, installs an LSP auto-attach autocmd when `lsp.auto_attach.enabled` is true, and loads `zk/commands/builtin.lua` (registers all `:Zk*` commands).

### Example — default setup
```lua
require("zk").setup()
```

### Example — advanced setup with picker theme and LSP overrides
```lua
require("zk").setup({
  picker = "telescope",
  picker_options = {
    telescope = require("telescope.themes").get_ivy(),
  },
  lsp = {
    config = {
      cmd = { "zk", "lsp" },
      on_attach = function(client, bufnr)
        -- custom LSP keymaps
      end,
    },
  },
  tags = { multi_select_strategy = "OR" },
})
```

### Notes
This plugin starts the LSP server itself — do not also call `require("lspconfig").zk.setup()` (see `doc/zk.txt`).
```

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

### buf_add(bufnr)

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/lsp.md

Starts the LSP client if necessary and attaches the given buffer to the zk LSP client. This is the callback used by the auto-attach autocmd installed by zk.setup.

```APIDOC
## `buf_add(bufnr)`

### Description
Starts the LSP client if necessary and attaches the given buffer to the zk LSP client. This is the callback used by the auto-attach autocmd installed by zk.setup.

### Signature
```lua
---Starts an LSP client if necessary, and attaches the given buffer.
---@param bufnr number
function M.buf_add(bufnr)
  bufnr = bufnr or 0
  M.start()

  if client_id then
    vim.lsp.buf_attach_client(bufnr, client_id)
  end
end
```

### Parameters
- **bufnr** (number) - Optional - Buffer to attach the zk client to. Defaults to `0` (current buffer).

### Return
`nil`. Calls `start()` and then `vim.lsp.buf_attach_client(bufnr, client_id)`.

### Example — basic call
```lua
require("zk.lsp").buf_add(0) -- attach current buffer
```
```

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

### Basic call example: get_lsp_location_from_selection()

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/util.md

Shows a basic call to `get_lsp_location_from_selection()` from the `zk.util` module. It retrieves the LSP location object and prints the URI and start position of the selection.

```lua
local loc = require("zk.util").get_lsp_location_from_selection()
print(loc.uri, loc.range.start.line, loc.range.start.character)
```

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

### zk.new() basic call example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/zk.md

Creates a new note in the 'daily' directory with yesterday's date and opens it.

```lua
require("zk").new({ dir = "daily", date = "yesterday" })
```

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

### zk-nvim command examples

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

Examples of using zk-nvim commands with options, including creating notes, listing notes, inserting links, and searching. Note that :ZkNewFromTitleSelection must be called with the '<,'> range, and :ZkMatch without a match option falls back to the word under the cursor or visual selection.

```vim
:ZkNew { dir = "daily", date = "yesterday" }
:ZkNotes { createdAfter = "3 days ago", tags = { "work" } }
:'<,'>ZkNewFromTitleSelection " this will use your last visual mode selection. Note that you *must* call this command with the '<,'> range.
:ZkCd
:ZkMatch { match = { "foo", "bar" } } " search notes matching "foo" or "bar"
:ZkMatch { sort = { "created" } } " no match given, falls back to the word under the cursor (or visual selection)
```

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

### client() basic call example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/lsp.md

Retrieves the LSP client and prints its id and offset_encoding if it exists.

```lua
local client = require("zk.lsp").client()
if client then
  print(client.id, client.offset_encoding)
end
```

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

### fzf picker: show_tag_picker example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/pickers.md

Example of calling show_tag_picker from the fzf backend with a tag list, options, and a callback that prints the selected tag name.

```lua
require("zk.pickers.fzf").show_tag_picker(
  { { name = "work", note_count = 1 } },
  { title = "Tags", multi_select = true },
  function(tags) vim.notify(vim.inspect(tags)) end
)
```

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

### Install zk-nvim with packer.nvim

Source: https://github.com/zk-org/zk-nvim/blob/main/doc/zk.txt

Install the zk-nvim plugin using packer.nvim. Requires Neovim >= 0.10.0 and zk >= 0.14.1.

```lua
use("zk-org/zk-nvim")
```

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

### Basic call example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/util.md

Shows a basic call to `resolve_notebook_path` with the current buffer. It notifies the user if a candidate path is found.

```lua
local p = require("zk.util").resolve_notebook_path(0)
if p then vim.notify("candidate notebook path: " .. p) end
```

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

### Example usage of built-in commands with options

Source: https://github.com/zk-org/zk-nvim/blob/main/doc/zk.txt

Shows how to pass options as a Lua table to commands. Note that :ZkNewFromTitleSelection must be called with the '<,'> range.

```vim
:ZkNew { dir = "daily", date = "yesterday" }
:ZkNotes { createdAfter = "3 days ago", tags = { "work" } }
:'<,'>ZkNewFromTitleSelection " this will use your last visual mode selection. Note that you *must* call this command with the '<,'> range.
:ZkCd
```

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

### Install zk-nvim with vim-plug

Source: https://github.com/zk-org/zk-nvim/blob/main/doc/zk.txt

Install the zk-nvim plugin using vim-plug. Requires Neovim >= 0.10.0 and zk >= 0.14.1.

```vim
Plug "zk-org/zk-nvim"
```

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

### zk.index() basic call example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/zk.md

Re-indexes the notebook with default options and notifies with the stats.

```lua
require("zk").index()
```

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

### Example global key mappings for zk

Source: https://github.com/zk-org/zk-nvim/blob/main/doc/zk.txt

Global key mappings for zk commands. Add these to your main Neovim config.

```lua
local opts = { noremap=true, silent=false }
-- Create a new note after asking for its title.
vim.api.nvim_set_keymap("n", "<leader>zn", "<Cmd>ZkNew { title = vim.fn.input('Title: ') }<CR>", opts)
-- Open notes.
vim.api.nvim_set_keymap("n", "<leader>zo", "<Cmd>ZkNotes { sort = { 'modified' } }<CR>", opts)
-- Open notes associated with the selected tags.
vim.api.nvim_set_keymap("n", "<leader>zt", "<Cmd>ZkTags<CR>", opts)
-- Search for the notes matching a given query.
vim.api.nvim_set_keymap("n", "<leader>zf", "<Cmd>ZkNotes { sort = { 'modified' }, match = { vim.fn.input('Search: ') } }<CR>", opts)
-- Search for the notes matching the current visual selection.
vim.api.nvim_set_keymap("v", "<leader>zf", ":'<,'>ZkMatch<CR>", opts)
```

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

### new basic call example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/api.md

Calls `require("zk.api").new` with a title, directory, and date, printing the absolute path of the created note.

```lua
require("zk.api").new(nil, { title = "Daily note", dir = "daily", date = "today" }, function(err, res)
  if err then return end
  print(res.path) -- absolute path of the new note
end)
```

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

### Initialize zk.util module table

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/util.md

Initializes the module table for zk.util. This is the starting point of the module definition.

```lua
local M = {}
```

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

### root_pattern basic call example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/root_pattern_util.md

Creates a matcher for the .zk pattern and uses it on the current file's path. Prints the root if found. Equivalent to zk.util.notebook_root.

```lua
local matcher = require("zk.root_pattern_util").root_pattern(".zk")
local root = matcher(vim.fn.expand("%:p"))
if root then print("root:", root) end
```

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

### root_pattern multiple patterns example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/root_pattern_util.md

Creates a matcher for both .git and .zk patterns and calls it on a sample path. Returns the nearest ancestor containing any of the patterns.

```lua
local find = require("zk.root_pattern_util").root_pattern({ ".git", ".zk" })
print(find("/tmp/nb/inbox/scratch.md"))
```

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

### Minimal zk-nvim setup with defaults

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/configuration.md

Use this minimal configuration to enable zk-nvim with default settings, which uses vim.ui.select as the picker. Call require("zk").setup() with no arguments to apply defaults.

```lua
require("zk").setup()
```

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

### Location (LSP) object structure

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/types.md

Example of the LSP Location object as built by zk.util. The uri field is a string like 'file:///home/user/notes/a.md', and range is a table with start and end positions, each with line and character (0-based).

```lua
{
  uri = params.textDocument.uri,       -- string, e.g. "file:///home/user/notes/a.md"
  range = { start = { line, character }, ["end"] = { line, character } }, -- 0-based
}
```

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

### Basic Telescope zk commands

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/telescope-extension.md

Shows how to load the extension and use the `:Telescope zk` commands for notes and tags with various options.

```lua
require("telescope").load_extension("zk")
```

```viml
:Telescope zk notes
:Telescope zk notes createdAfter=3\ days\ ago
:Telescope zk tags
:Telescope zk tags created=today
```

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

### Single selection with error handling

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/zk.md

Example of using `pick_notes` with `multi_select = false` to get a single note. The callback edits the note if selected. Errors from the LSP request abort via `assert(not err, tostring(err))`.

```lua
local zk = require("zk")
zk.pick_notes({ tags = { "work" } }, { multi_select = false }, function(note)
  if note then
    vim.cmd("edit " .. note.absPath)
  end
end)
-- Errors from the LSP request abort via `assert(not err, tostring(err))`.
```

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

### Direct use example for M.path functions

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/root_pattern_util.md

Shows how to use `zk.root_pattern_util.path` directly: `join` flattens arguments and joins with `/`, `exists` checks a path, and `iterate_parents` yields existing ancestor directories.

```lua
local p = require("zk.root_pattern_util").path
print(p.join("/home/user", { "notes", ".zk" })) -- /home/user/notes/.zk
print(p.exists("/tmp") ~= false)                 -- true
for parent in p.iterate_parents("/home/user/notes") do
  print(parent)
end
```

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

### Minimal config directory structure

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

Create a new directory init-zk with this structure to test zk-nvim with a minimal configuration.

```text
.
├── init.lua
└── notebook
    └── .zk
        ├── config.toml
        ├── notebook.db
        └── templates
            └── default.md
```

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

### minipick picker: show_note_picker example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/pickers.md

Shows how to invoke the minipick backend's show_note_picker with a note list, options, and a callback that opens the selected note's absolute path.

```lua
require("zk.pickers.minipick").show_note_picker(notes, { title = "Pick", multi_select = false }, function(n)
  if n then vim.cmd("e " .. n.absPath) end
end)
```

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

### Initialize zk.lsp module

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/lsp.md

Initializes the module-level client_id and configuration requirements.

```lua
local config = require("zk.config")

local client_id = nil

local M = {}
```

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

### pick_tags basic call example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/ui.md

Example of calling `pick_tags` with a single tag and a callback that notifies the tag name.

```lua
require("zk.ui").pick_tags({ { name = "work", note_count = 12 } }, nil, function(tag)
  vim.notify("tag: " .. tag.name)
end)
```

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

### search_ancestors(startpath, func)

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/root_pattern_util.md

Searches upward from a starting path, invoking a predicate on each ancestor directory, and returns the first path for which the predicate returns truthy. The search includes the starting path itself and is guarded against infinite loops.

```APIDOC
## search_ancestors(startpath, func)

### Description
Searches upward from a starting path, invoking a predicate on each ancestor directory, and returns the first path for which the predicate returns truthy. The search includes the starting path itself and is guarded against infinite loops.

### Signature
```lua
function M.search_ancestors(startpath, func)
```

### Parameters
- **startpath** (string) - Required - Path to begin searching from.
- **func** (function(string) -> truthy?) - Required - Predicate called with each candidate path; validated with `vim.validate("func", func, "function")`.

### Return
- **string?** - The first path (starting with `startpath` itself) for which `func` returns truthy, else `nil`. A guard of 100 iterations prevents infinite loops.

### Example
```lua
local rp = require("zk.root_pattern_util")
local found = rp.search_ancestors("/tmp/nb/sub", function(path)
  return vim.fn.glob(rp.path.join(rp.path.escape_wildcards(path), ".zk"), true, true) ~= ""
end)
```
```

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

### zk.ui.get_pick_notes_list_api_selection()

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/index.md

Gets the selection from the picker API.

```APIDOC
## zk.ui.get_pick_notes_list_api_selection()

### Description
Gets the selection from the picker API.

### Method
get_pick_notes_list_api_selection

### Returns
- **selection** (any) - The selection.

### Usage
```lua
local selection = require("zk.ui").get_pick_notes_list_api_selection()
```
```

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

### zk.commands.get(name)

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/index.md

Gets a registered user command.

```APIDOC
## zk.commands.get(name)

### Description
Gets a registered user command.

### Method
get

### Parameters
- **name** (string) - Required - The command name.

### Returns
- **command** (function) - The command implementation.

### Usage
```lua
local cmd = require("zk.commands").get("MyCommand")
```
```

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

### Setup zk-nvim with custom configuration

Source: https://github.com/zk-org/zk-nvim/blob/main/doc/zk.txt

Configure the picker and LSP options. The picker can be "telescope", "fzf", "fzf_lua", "minipick", "snacks_picker", or "select" (vim.ui.select). The LSP config is passed to vim.lsp.start_client(config). Auto-attach is enabled for markdown filetypes by default.

```lua
require("zk").setup({
  -- Can be "telescope", "fzf", "fzf_lua", "minipick", "snacks_picker", 
  -- or select" (`vim.ui.select`). It's recommended to use "telescope", 
  -- "fzf", "fzf_lua", "minipick", or "snacks_picker".
  picker = "select",
  lsp = {
    -- `config` is passed to `vim.lsp.start_client(config)`
    config = {
      cmd = { "zk", "lsp" },
      name = "zk",
      -- 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" },
    },
  },
})
```

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

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

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/index.md

Loads the legacy telescope extension for zk.

```APIDOC
## require("telescope").load_extension("zk")

### Description
Loads the legacy telescope extension for zk.

### Method
load_extension

### Parameters
- **name** (string) - Required - The extension name, must be "zk".

### Usage
```lua
require("telescope").load_extension("zk")
```
```

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

### Module header and initialization for zk.root_pattern_util

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/root_pattern_util.md

Sets up the module with local references to `vim` and `uv` (from `vim.loop`). Includes a note that the code is copied from nvim-lspconfig until merged into Neovim core.

```lua
-- NOTE: everything in this module is copied from nvim-lspconfig (https://github.com/neovim/nvim-lspconfig)
-- NOTE: we need this util until the code from lspconfig is merged into core

local vim = vim
local uv = vim.loop

local M = {}
```

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

### buf_add() basic call example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/lsp.md

Attaches the current buffer to the zk LSP client.

```lua
require("zk.lsp").buf_add(0) -- attach current buffer
```

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

### Minimal init.lua for zk-nvim with lazy.nvim

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

Paste this into init.lua to set up a minimal Neovim config that redirects runtime paths to /tmp and bootstraps lazy.nvim with zk-nvim and nvim-lspconfig. It sets mapleader and maplocalleader before loading lazy.nvim.

```lua
-- Redirect Neovim runtime paths to /tmp
vim.env.XDG_CONFIG_HOME = "/tmp/nvim/config"
vim.env.XDG_DATA_HOME = "/tmp/nvim/data"
vim.env.XDG_STATE_HOME = "/tmp/nvim/state"
vim.env.XDG_CACHE_HOME = "/tmp/nvim/cache"

-- Bootstrap lazy.nvim
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not (vim.uv or vim.loop).fs_stat(lazypath) then
  local lazyrepo = "https://github.com/folke/lazy.nvim.git"
  local out = vim.fn.system({ "git", "clone", "--filter=blob:none", "--branch=stable", lazyrepo, lazypath })
  if vim.v.shell_error ~= 0 then
    vim.api.nvim_echo({
      { "Failed to clone lazy.nvim:\n", "ErrorMsg" },
      { out, "WarningMsg" },
      { "\nPress any key to exit..." },
    }, true, {})
    vim.fn.getchar()
    os.exit(1)
  end
end
vim.opt.rtp:prepend(lazypath)

-- Make sure to setup `mapleader` and `maplocalleader` before
-- loading lazy.nvim so that mappings are correct.
-- This is also a good place to setup other settings (vim.opt)
vim.g.mapleader = " "
vim.g.maplocalleader = "\\"

-- Setup lazy.nvim
require("lazy").setup({
	{ "neovim/nvim-lspconfig" },
	{ "zk-org/zk-nvim", name = "zk", opts = {}, },
	-- automatically check for plugin updates
	checker = { enabled = true },
})
```

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

### Call external_client

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/lsp.md

Basic usage example to retrieve and print the ID of an active external zk client.

```lua
local id = require("zk.lsp").external_client()
if id then print("using external zk client", id) end
```

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

### zk.index() with custom callback example

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/zk.md

Re-indexes the notebook and uses a custom callback to display note and tag counts.

```lua
require("zk").index({ notebook_path = "~/notes" }, function(stats)
  vim.notify(string.format("Indexed %s notes, %s tags", stats.noteCount, stats.tagCount))
end)
```

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

### get_pick_notes_list_api_selection inside custom picker flow

Source: https://github.com/zk-org/zk-nvim/blob/main/_autodocs/api-reference/ui.md

Example of using `get_pick_notes_list_api_selection` with custom options and handling multi-select results.

```lua
local options = { picker = "fzf_lua", multi_select = true, title = "Choose" }
api.list(nil, { selection = require("zk.ui").get_pick_notes_list_api_selection(options) }, function(err, notes)
  if not err then
    require("zk.ui").pick_notes(notes, options, function(sel)
      -- multi-select: sel is an array
      vim.tbl_map(function(n) return n.absPath end, sel)
    end)
  end
end)
```

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

### require("zk").index(options)

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

Indexes the notebook. Accepts an optional table of options.

```APIDOC
## require("zk").index(options)

### Description
Indexes the notebook.

### Method
N/A (Lua function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (table) - Optional - Additional options for the operation.

### Request Example
```lua
require("zk").index()
```

### Response
#### Success Response (200)
No return value.

#### Response Example
No response body.

ERROR HANDLING:
- No error handling specified.
```
Tokens:
Raw