# I wrote a (hopefully) complete guide to writing your first kakrc **URL:** \ **Category:** Resources\ **Created:** [April 23, 2023, 12:24am UTC](https://discuss.kakoune.com/t/i-wrote-a-hopefully-complete-guide-to-writing-your-first-kakrc/2214 "2023-04-23T00:24:02Z")\ **Posts on this page:** 8\ **Page:** 1
**Author:** ![secondary-smiles](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/secondary-smiles/32/1183_2.png) [@secondary-smiles](https://discuss.kakoune.com/u/secondary-smiles)\ **Post date:** [April 23, 2023, 12:24am UTC](https://discuss.kakoune.com/t/i-wrote-a-hopefully-complete-guide-to-writing-your-first-kakrc/2214/1 "2023-04-23T00:24:02Z")
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](https://lightblog.dev/articles/writing-your-first-kakrc) ---
**Author:** ![Screwtapello](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/screwtapello/32/12_2.png) [@Screwtapello](https://discuss.kakoune.com/u/Screwtapello)\ **Post date:** [April 23, 2023, 7:50am UTC](https://discuss.kakoune.com/t/i-wrote-a-hopefully-complete-guide-to-writing-your-first-kakrc/2214/2 "2023-04-23T07:50:37Z")
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}' > > ``` A cleaner way to do this might be: ``` map -docstring "copy to system pboard" global user y ' pbcopy' ``` 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 ", pbcopyret" ' ``` - `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` - `ret` 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! ---
**Author:** ![secondary-smiles](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/secondary-smiles/32/1183_2.png) [@secondary-smiles](https://discuss.kakoune.com/u/secondary-smiles)\ **Post date:** [April 23, 2023, 4:41pm UTC](https://discuss.kakoune.com/t/i-wrote-a-hopefully-complete-guide-to-writing-your-first-kakrc/2214/3 "2023-04-23T16:41:45Z")
Thanks! I even learned a bit from these tips. Edits made, thanks for the help `:)` ---
**Author:** ![Kratacoa](https://discuss.kakoune.com/letter_avatar_proxy/v4/letter/k/b5ac83/32.png) [@Kratacoa](https://discuss.kakoune.com/u/Kratacoa)\ **Post date:** [April 24, 2023, 10:44pm UTC](https://discuss.kakoune.com/t/i-wrote-a-hopefully-complete-guide-to-writing-your-first-kakrc/2214/4 "2023-04-24T22:44:09Z")
Very nice guide, I’ll be referring people to it from now on! ---
**Author:** ![blaisep](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/blaisep/32/1610_2.png) [@blaisep](https://discuss.kakoune.com/u/blaisep)\ **Post date:** [January 11, 2026, 6:38pm UTC](https://discuss.kakoune.com/t/i-wrote-a-hopefully-complete-guide-to-writing-your-first-kakrc/2214/5 "2026-01-11T18:38:22Z")
Hi @secondary-smiles , I’m new to Kakoune (old to just about everything else) and was hoping to use this `HOWTO` but the link seem dead with no redirect. Is it available somewhere else? Thank you ---
**Author:** ![vrugar0](https://discuss.kakoune.com/letter_avatar_proxy/v4/letter/v/439d5e/32.png) [@vrugar0](https://discuss.kakoune.com/u/vrugar0)\ **Post date:** [January 12, 2026, 2:20pm UTC](https://discuss.kakoune.com/t/i-wrote-a-hopefully-complete-guide-to-writing-your-first-kakrc/2214/6 "2026-01-12T14:20:31Z")
It is probably this article - [frog.ski | Writing Your First Kakoune Config (kakrc)](https://frog.ski/blog/writing-your-first-kakrc) ---
**Author:** ![blaisep](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/blaisep/32/1610_2.png) [@blaisep](https://discuss.kakoune.com/u/blaisep)\ **Post date:** [January 15, 2026, 9:24pm UTC](https://discuss.kakoune.com/t/i-wrote-a-hopefully-complete-guide-to-writing-your-first-kakrc/2214/7 "2026-01-15T21:24:59Z")
Thank you so much, this looks like a very helpful HOWTO. I want to tell frog (@secondary-smiles ?) that the link to their dotfile repo is broken: [https://github.com/secondary-smiles/.dots/blob/main/pkg/kakoune/kakrc](https://github.com/secondary-smiles/.dots/blob/main/pkg/kakoune/kakrc) ---
**Author:** ![blaisep](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/blaisep/32/1610_2.png) [@blaisep](https://discuss.kakoune.com/u/blaisep)\ **Post date:** [May 14, 2026, 9:44pm UTC](https://discuss.kakoune.com/t/i-wrote-a-hopefully-complete-guide-to-writing-your-first-kakrc/2214/8 "2026-05-14T21:44:18Z")
This is also a good place to get started with a kakrc: > **[The first two hours of Kakoune in two minutes](https://kakoune-editor.github.io/community-articles/2021/01/01/first_two_hours_in_two_minutes.html)** > > Learning a new editor can be a daunting task, especially when coming over from a non-modal editor. I personally started with Emacs, and it took me weeks to be productive when I started using Vim. The modal paradigm is a powerful tool, but picking it...