zk/docs/editors-integration.md

# Editors integration

There are several extensions available to integrate `zk` in your favorite editor:

* [`zk-nvim`](https://github.com/zk-org/zk-nvim) for Neovim 0.5+
* [`zk-vscode`](https://github.com/zk-org/zk-vscode) for Visual Studio Code

## Language Server Protocol

`zk` ships with a [Language Server](https://microsoft.github.io/language-server-protocol/overviews/lsp/overview/) to provide basic support for any LSP-compatible editor. The currently supported features are:

* Auto-complete Markdown links with `[[` (setup wiki-links in the [note formats configuration](note-format.md))
* Auto-complete [hashtags and colon-separated tags](tags.md).
* Preview the content of a note when hovering a link.
* Navigate in your notes by following internal links.
* Create a new note using the current selection as title.
* Diagnostics for dead links and wiki-links titles.
* [And more to come...](https://github.com/zk-org/zk/issues/22)
  
You can configure some of these features in your notebook's [configuration file](config-lsp.md).

### Editor LSP configurations

To start the Language Server, use the `zk lsp` command. Refer to the following sections for editor-specific examples. [Feel free to share the configuration for your editor](https://github.com/zk-org/zk/issues/22).

#### Vim and Neovim

##### Vim and Neovim 0.4

With [`coc.nvim`](https://github.com/neoclide/coc.nvim), run `:CocConfig` and add the following in the settings file:

<details><summary><tt>coc-settings.json</tt></summary>

```jsonc
{
  // Important, otherwise link completion containing spaces and other special characters won't work.
  "suggest.invalidInsertCharacters": [],

  "languageserver": {
    "zk": {
      "command": "zk",
      "args": ["lsp"],
      "trace.server": "messages",
      "filetypes": ["markdown"]
    },
  }
}
```
</details>

Here are some additional useful key bindings and custom commands:

<details><summary><tt>~/.config/nvim/init.vim</tt></summary>

```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>
```
</details>

##### Neovim 0.5 built-in LSP client

Using [`nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig):

<details><summary><tt>~/.config/nvim/init.lua</tt></summary>

```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 })
```
</details>

#### Sublime Text

Install the [Sublime LSP](https://github.com/sublimelsp/LSP) package, then run the **Preferences: LSP Settings** command. Add the following to the settings file:

<details><summary><tt>LSP.sublime-settings</tt></summary>

```jsonc
{
  "clients": {
    "zk": {
      "enabled": true,
      "command": ["zk", "lsp"],
      "languageId": "markdown",
      "scopes": [ "source.markdown" ],
      "syntaxes": [ "Packages/MarkdownEditing/Markdown.sublime-syntax" ]
    }
  }
}
```
</details>

#### Visual Studio Code

Install the [`zk-vscode`](https://marketplace.visualstudio.com/items?itemName=mickael-menu.zk-vscode) extension from the Marketplace.

### Custom commands

Using `zk`'s LSP custom commands, you can call `zk` commands right from your editor. Please refer to your editor's documentation on how to bind keyboard shortcuts to custom LSP commands.

#### `zk.index`

This LSP command calls `zk index` to refresh your notebook's index. It can be useful to make sure that the auto-completion is up-to-date. `zk.index` takes two arguments:

1. A path to a file or directory in the notebook to index.
2. <details><summary>(Optional) A dictionary of additional options (click to expand)</summary>
    
    | Key     | Type    | Description                       |
    |---------|---------|-----------------------------------|
    | `force` | boolean | Reindexes all the notes when true |
    </details>

`zk.index` returns a dictionary of indexing statistics.

#### `zk.new`

This LSP command calls `zk new` to create a new note. It can be useful to quickly create a new note with a key binding. `zk.new` takes two arguments:

1. A path to any file or directory in the notebook, to locate it.
2. <details><summary>(Optional) A dictionary of additional options (click to expand)</summary>
    
    | Key                       | Type                 | Description                                                                                                          |
    |---------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------|
    | `title`                   | string               | Title of the new note                                                                                                |
    | `content`                 | string               | Initial content of the note                                                                                          |
    | `dir`                     | string               | Parent directory, relative to the root of the notebook                                                               |
    | `group`                   | string               | [Note configuration group](config-group.md)                                                                          |
    | `template`                | string               | [Custom template used to render the note](template-creation.md)                                                      |
    | `extra`                   | dictionary           | A dictionary of extra variables to expand in the template                                                            |
    | `date`                    | string               | A date of creation for the note in natural language, e.g. "tomorrow"                                                 |
    | `edit`                    | boolean              | When true, the editor will open the newly created note (**not supported by all editors**)                            |
    | `dryRun`                  | boolean              | When true, `zk` will not actually create the note on the file system, but will return its generated content and path |
    | `insertLinkAtLocation`    | location<sup>1</sup> | A location in another note where a link to the new note will be inserted                                             |
    | `insertContentAtLocation` | location<sup>1</sup> | A location in another note where the content of the new note will be inserted                                        |

    1. The `location` type is an [LSP Location object](https://microsoft.github.io/language-server-protocol/specification#location), for example:

    ```json
    {
        "uri":"file:///Users/mickael/notes/9se3.md",
        "range": {
            "end":{"line": 5, "character":149},
            "start":{"line": 5, "character":137}
        }
    }
    ```
    </details>

`zk.new` returns a dictionary with two properties:

* `path` containing the absolute path to the created note.
* `content` containing the raw content of the created note.

#### `zk.link`

This LSP command allows editors to tap into the note linking mechanism. It takes three arguments:

1. A `path` to any file in the notebook that will be linked to
2. An LSP `location` object that points to where the link will be inserted
3. An optional title of the link. If `title` is not provided, the title of the note will be inserted instead

`zk.link` returns a JSON object with the path to the linked note, if the linking was successful.

**Note**: This command is _not_ exposed in the command line. This command is targeted at editor / plugin authors to extend zk functionality.

#### `zk.list`

This LSP command calls `zk list` to search a notebook. It takes two arguments:

1. A path to any file or directory in the notebook, to locate it.
2. <details><summary>A dictionary of additional options (click to expand)</summary>
    
  | Key                | Type           | Required?   | Description                                                                                               |
  | ------------------ | -------------- | ----------- | -------------------------------------------------------------------------                                 |
  | `select`           | string array   | Yes         | List of note fields to return<sup>1</sup>                                                                 |
  | `hrefs`            | string array   | No          | Find notes matching the given path, including its descendants                                             |
  | `limit`            | integer        | No          | Limit the number of notes found                                                                           |
  | `match`            | string array   | No          | Terms to search for in the notes                                                                          |
  | `exactMatch`       | boolean        | No          | (deprecated: use `matchStrategy`) Search for exact occurrences of the `match` argument (case insensitive) |
  | `matchStrategy`    | string         | No          | Specify match strategy, which may be "fts" (default), "exact" or "re"                                     |
  | `excludeHrefs`     | string array   | No          | Ignore notes matching the given path, including its descendants                                           |
  | `tags`             | string array   | No          | Find notes tagged with the given tags                                                                     |
  | `mention`          | string array   | No          | Find notes mentioning the title of the given ones                                                         |
  | `mentionedBy`      | string array   | No          | Find notes whose title is mentioned in the given ones                                                     |
  | `linkTo`           | string array   | No          | Find notes which are linking to the given ones                                                            |
  | `linkedBy`         | string array   | No          | Find notes which are linked by the given ones                                                             |
  | `orphan`           | boolean        | No          | Find notes which are not linked by any other note                                                         |
  | `related`          | string array   | No          | Find notes which might be related to the given ones                                                       |
  | `maxDistance`      | integer        | No          | Maximum distance between two linked notes                                                                 |
  | `recursive`        | boolean        | No          | Follow links recursively                                                                                  |
  | `created`          | string         | No          | Find notes created on the given date                                                                      |
  | `createdBefore`    | string         | No          | Find notes created before the given date                                                                  |
  | `createdAfter`     | string         | No          | Find notes created after the given date                                                                   |
  | `modified`         | string         | No          | Find notes modified on the given date                                                                     |
  | `modifiedBefore`   | string         | No          | Find notes modified before the given date                                                                 |
  | `modifiedAfter`    | string         | No          | Find notes modified after the given date                                                                  |
  | `sort`             | string array   | No          | Order the notes by the given criterion                                                                    |

    1. As the output of this command might be very verbose and put a heavy load on the LSP client, you need to explicitly set which note fields you want to receive with the `select` option. The following fields are available: `filename`, `filenameStem`, `path`, `absPath`, `title`, `lead`, `body`, `snippets`, `rawContent`, `wordCount`, `tags`, `metadata`, `created`, `modified` and `checksum`.

    </details>

`zk.list` returns the found notes as a JSON array.

#### `zk.tag.list`

This LSP command calls `zk tag list` to return the list of tags in a notebook. It takes two arguments:

1. A path to any file or directory in the notebook, to locate it.
2. <details><summary>(Optional) A dictionary of additional options (click to expand)</summary>
    
    | Key    | Type         | Required? | Description                                      |
    |--------|--------------|-----------|--------------------------------------------------|
	| `sort` | string array | No        | Order the tags by the given criteria<sup>1</sup> |

    1. The available sort criteria are `name` and `note-count`. You can change the order by appending `-` or `+` to the criterion.

    </details>

`zk.tag.list` returns the tags as a JSON array.