I wrote a (hopefully) complete guide to writing your first kakrc

Resources
1

Hey all,
I’m a past user of Vim and Helix who recently switched to Kakoune.
However, when I was switching over, I initially had a hard time writing a kakrc as I couldn’t find any step-by-step tutorials on useful commands for configuring Kakoune. I also didn’t know how to navigate the :docs for the same reason.

I eventually figured it out and decided to write a nice long article on everything that I think someone would need to get started with configuring Kakoune.

Here’s the link

9 Likes
2

Congratulations on making the switch, and thank you for taking the time to write about your experiences. Kakoune has a lot of documentation, but most of it’s reference material rather than tutorials, and it’s good to have instructions written by different people from different points of view.

I did see a few minor things I wanted to point out for completeness, though. I hope these can help you (and other people reading your article) understand Kakoune a little better.

When ran, kak will search for a kakrc file in your configuration folder (usually ~/.config/kak/kakrc), and load it up. Then, kak will search for the autoload folder(s) and recursively load all .kak files in it.

Actually, it’s the other way around: Kakoune loads the autoload contents first and the kakrc file last, so that your kakrc can set any configuration for your plugins as well as configuration for Kakoune’s standard features.

The global scope refers to every instance of kak currently running.

This is not entirely correct. Each UNIX user account on a given system can have multiple Kakoune “sessions” (listed in the output of kak -l), and each session can have multiple “clients” (launched with :new from inside Kakoune, or launched with kak -c sessionname from a terminal).

If you open a terminal, start kak and then do :set-option global scrolloff 10 then it will be set for every client attached to that session, but it won’t affect clients attached to any other sessions that happen to be running.

If you put that command in your kakrc then it will affect every session you start from then on, but that’s not quite the same thing.

The more astute among you may have noticed that the commands in that mapping have a space separating the : colon and the actual command. In Kakoune we do this when we don’t want the command saved in the history (access the history by typing : and pressing the up/down arrows).

I’m not sure it’s in the most recent stable version (yet) but at least the next version of Kakoune does not include commands typed by mappings or by execute-keys in the interactive command history, whether or not there’s a leading space.

And one more

map -docstring "copy to system pboard" global user y ':  nop %sh{printf "%s" "$kak_selection" | pbcopy}<ret>'

A cleaner way to do this might be:

map -docstring "copy to system pboard" global user y '<a-|> pbcopy<ret>'

The difference is that the original version only copies the main selection to the clipboard, but it breaks if you have selected more text than can fit in an environment variable. The second version copies each selection to the clipboard one-by-one (so only the last selection will remain) but it should work even with very large selections.

You could also do:

map -docstring "copy to system pboard" global user y ': execute-keys -draft ",<a-|> pbcopy<lt>ret<gt>" <ret>'
  • execute-keys takes a sequences of keys to press, just like the right-hand side of a mapping
  • -draft (which is not available for mappings) causes the keys to be executed in a “draft context” which is somewhat hazily defined, but in this case means that any changes to which text is selected will be automatically undone when execute-keys finishes
  • , drops all selections but the main one, so that they won’t be uselessly piped to pbcopy
  • <lt>ret<gt> means that the mapping will type those literal keys, so that execute-keys will interpret them as an instruction to press Return.

Here’s my save-buffer command:

...
info 'file saved at %sh{date}'
...

Like shell, Kakoune does not expand things inside single quotes. You’ll want double-quotes instead:

info "file saved at %sh{date}"

Another hook I have enabled is soft-wrapping text in .md files.

...
add-highlighter -override global/ wrap -word
...

If you want to do the “automatically remove highlighters when the filetype changes” trick, you should explicitly name the highlighters you create, since Kakoune doesn’t guarantee any particular naming scheme. The current version of Kakoune will name this highlighter global/wrap_-word but the nested hook tries to remove global/wrap which probably doesn’t exist. Additionally, it’s not a good idea to set things at the global scope from within a Window hook - you could mess up things in other windows, or other buffers in this window. I recommend something like:

add-highlighter -override window/markdown-wrap wrap -word

Then you can remove it later with:

remove-highlighter window/markdown-wrap

I hope that all helps!

4 Likes
3

Thanks! I even learned a bit from these tips.

Edits made, thanks for the help :)

4

Very nice guide, I’ll be referring people to it from now on!

1 Like