Some initial thoughts on writing plugins

Writing-Plugins.md

@@ -0,0 +1,30 @@
+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`.
+