Improve docs in non-native zk commands

[Dioprz]

Verify

• I searched the existing discussions for similar ideas

Share your idea or feature request

Hi,

Do you think it's possible to add any hint in the documentation to point users where to find the expected keys in the options parameter? My main concern is in non-native zk commands, because currently the documentation includes this:

The options parameter can be any valid Lua expression that evaluates to a table. For a list of available options, refer to the zk docs.

However, for commands like ZkCd, there's no indication of what the function expects. For example, I need to go to the cd function code to see that this line

zk-nvim/lua/zk.lua

Line 55 in 1f331d9

local notebook_path = options.notebook_path or util.resolve_notebook_path(0)

Needs a notebook_path key in the table, so the proper way to call it is this

:ZkCd {notebook_path = "path_to_notebook"}

But before discovering this, I tried

:ZkCd "path_to_notebook"
:ZkCd {"path_to_notebook"}
:ZkCd {path = "path_to_notebook"}

Without any succes.

I'm open to write the PR to add this if you want, but I would appreciate it if you could show me what format the options should have.

Thanks a lot for this plugin, has been very useful to me.

[tjex]

i tried grepping for the documentation you quoted options parameter can be any, but found nothing... Not saying it's not there, but could you point me to where this documentation actually is?

It sounds like you already found the correct format for passing options though?

It's the same throughout: <cmd> {<option_name> = "<option value"}

So :ZkNew {title = "a custom title", dir = "./dir/foo"}

[Dioprz]

@tjex Sure, you can find the documentation in the README, here.

However, after reading it again, I noticed the next line does answer my question, but in a way I didn't initially understand:

The options parameter can be any valid Lua expression that evaluates to a table. For a list of available options, refer to the zk docs. In addition, options.notebook_path can be used to explicitly specify a notebook by providing a path to any file or directory within the notebook; see Notebook Directory Discovery.

Let me clarify my suggestion:

1. zk-nvim exposes commands that mirror the native zk CLI program, such as ZkNew, ZkIndex, etc. These commands have corresponding API methods documented here.
2. However, some commands like ZkCd, ZkMatch, and potentially others, don't have direct zk.cd or zk.match LSP command equivalents. Instead, they use specific implementations of existing zk LSP custom commands (or none at all, like ZkCd). These can be tricky to configure without prior knowledge of the zk CLI tool, as you need to figure out which LSP command to use and the correct parameters.
3. In my case, I struggled to figure out how to provide the notebook path for the ZkCd command. I had to dig into the code to find the required table key (notebook_path).
4. My proposal is to enhance the documentation for each zk-nvim command, explicitly stating where to find the relevant options. For example:

zk-nvim command	zk LSP command used	Options Reference
ZkNotes	zk.list	zk docs - zk.list
ZkMatch	zk.list	zk docs - zk.list
ZkCd	None	notebook_path (see Notebook Directory Discovery)

This would help new users quickly identify the correct options for customization.

I understand if this doesn't resonate with you, but I wanted to share my experience and where I encountered friction when configuring the plugin. I'm not familiar with the zk CLI tool (and only discovered it through your awesome plugin!).

I hope this is clearer! Let me know what you think.

[tjex]

Ok, that makes sense. Thanks for being so thorough.
I agree that this section of the readme is a bit convoluted. It also stumped me when I was getting to know zk myself! It would be great to have this cleared up and I think a table as you've suggested is a good approach 👍

I think it would clear it up even more to have a column for the matching zk cli command. It will also help to tie in the two worlds of cli and editor. Because using them together is really where zk shines.

I'm thinking something like this?

zk-nvim cmd	LSP reference	zk cli cmd
:ZkNotes	zk.list	zk list
:ZkMatch	zk.list	zk list --match
:ZkCd	none	none

If you're not a user of the zk cli / can't contribute that extra time, I'm happy to complete the cli column of your PR 👍

Thoughts?

[Dioprz]

That sounds great! Just one question, where will we put the notebook_path option for ZkCd, or commands non related with the zk cli tool? I'm considering adding a paragraph after the table to elaborate on important details. Would that be acceptable?

[tjex]

Good point. Well, in this case I would say a link to the notebook discovery section, and we then improve that section of the documentation.

So:

zk-nvim cmd	LSP reference	zk cli cmd
:ZkNotes	zk.list	zk list
:ZkMatch	zk.list	zk list --match
:ZkCd	see notebook discovery	none

... then in the readme add an example of ZkCd usage.
As far as I

Notebook Directory Discovery

When you run a notebook command, this plugin will look for a notebook in the following places and order:

the current buffer path (i.e. the file you are currently editing),
the current working directory,
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.

For example: :ZkCd {notebook_path = "~/docs/notebook"}