Writing Plugins

A Kakoune plugin is just a file with the .kak extension, living in the %val{config}/autoload directory (~/.config/kak/autoload by default, see Installing Plugins for details). If you have moved configuration out of your kakrc into the autoload directory to keep things tidy, you have already created a plugin!

Naming things

All commands created by plugins must live together, all options created by plugins must live together, all user-modes created by plugins must live together, etc. It's a good practice to prefix everything you declare or define with your plugin's name, to reduce the chance of collision with other plugins.

Do not create default mappings or hooks

It's tempting to add a bunch of map and hook commands to your plugin so that it automatically works from the moment it's installed. However, there's not that many key combinations available, and it's quite likely that you'll stomp on some other plugin, or the user's own configuration. While it's easy for the end-user to add new mappings of their own, it's difficult for them to figure out what mappings exist or which plugin introduced a mapping that broke their workflow. So don't do it.

Instead, your plugin should present its functionality as commands, that can be searched for with Kakoune's command-line, and with docstrings the user can read. You may also want to add a user-mode with mappings relevant to your plugin, if there's a set of very-frequently-used commands. You might also include "serving suggestion" mappings in your README or other documentation that people can paste into their kakrc and modify.

Finding resources

Your plugin may rely on data from an external file, or depend on an external script written in a more convenient language. Your plugin could hard-code a specific filesystem path to that data, but if your users install your plugin in a different location, things will break.

Luckily, Kakoune provides a solution, in the form of the %val{source} expansion. Let's say you have a plugin called "MyPlugin", which requires data in a CSV file. Your plugin might wind up with a filesystem structure like this:

kakoune-my-plugin
  |
  +- my-plugin.kak (our plugin script)
  |
  +- data.csv (the data our plugin requires)

At the top of my-plugin.kak, declare an option to store the path to the plugin directory. We use the -hidden flag because end-users don't need to see or modify this option, it's purely internal:

declare-option -hidden str my_plugin_path %sh{ dirname "$kak_source" }

Now %opt{my_plugin_path} contains the absolute path of the plugin directory, probably something like /home/somebody/.config/kak/autoload/kakoune-my-plugin (but the whole point is that it can vary). When a shell block in your plugin needs to refer to the data file, it can say $kak_opt_my_plugin_path/data.csv.