mirror of
https://github.com/mickael-menu/zk
synced 2024-11-17 09:25:44 +00:00
252 lines
14 KiB
Markdown
252 lines
14 KiB
Markdown
# 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.
|