Architecture of the plugin

[mickael-menu]

We can identify two layers in zk-nvim:

• A shared zk surface API.
• Opt-in adapters to bind various tools (Telescope, fzf, etc.) to the zk API.

zk Lua API

The low-level zk Lua API offers two kind of APIs:

• Basic functions wrapping the LSP server commands using nvim-lspconfig.
• Chromeless utilities that can be called with user bindings, e.g.
  • Jumping to the previous/next link
  • Open a link in a vertical/horizontal split or tab

Adapters

Depending on the plugin to bind to, the adapters could offer different kind of components/functions. To stay coherent across adapters, it could be useful to specify a shared catalog of APIs.

Building block components

These TUI components don't do anything besides presenting data on the screen and handling user interaction. Higher-level APIs are built upon them and the user can also use them directly for custom use cases.

• NotePicker displays the output of zk list and allows the user to select one (or more) notes.
  • The user can optionally filter the list.
  • Besides the main selection (<CR>), the caller should be able to add additional keybinding for additional actions, e.g:
    • Open in vertical/horizontal split.
    • Create a new note with the current filter query as title.
• TagPicker displays the output of zk tag list and allows the user to select one (or more) tags.
• NoteViewer can be used to preview a note without fully opening it. We can do that with the LSP client already but the interface is pretty limited.
• SnippetsViewer displays a list of notes and related snippets.
  • This could be used to automatically render a Backlinks dynamic section in (for example) a split buffer.
  • Or display the results of a match search query.

Higher-level APIs

This entry-point APIs can be directly used by the user with keybindings to answer common use cases. Ideally they should (when relevant) forward filtering options to zk, but offer sane defaults.

• browseNotes opens a NotePicker to edit note(s), it has a additional keybindings:
  • Create a new note with the current filter query as title.
  • Open in vertical/horizontal split or tabs.
• browseTags opens a TagPicker to select one or more tags, then call browseNotes to open notes with the selected tags.
• previewNote opens a NoteViewer with the link under the caret.
• linkToNote opens a NotePicker and insert a link to the selected note at the caret position.
  • This use case is handled with the LSP completion, but the NotePicker has better filtering options so might be more practical.

[smithbm2316]

I'm definitely a fan of this kind of architecture and think that it would allow for zk-nvim to help a wider range of users without having to support every Neovim fuzzy finder or plugin out of the box and make maintenance a nightmare. I'm hoping to continue making progress on the higher-level APIs that provide hackers with the tools that they need to start using zk with Neovim with less friction, even if they don't use Telescope.

[mickael-menu]

Yes that's what I had in mind, looking forward to it!