Master Key

Appearance

Master Keybindings ​

This defines version 2.0 of the master keybinding file format.

Master keybindings are TOML files composed of the following top-level fields:

  • header: top-level properties of the binding file
  • bind: an actual keybinding; extends the schema used by VSCode's keybindings.json
  • default: array that defines structured defaults that apply to keybinding subsets
  • mode: array describing behavior of keybinding modes
  • kind: array that documents broad categories of keys.
  • define: object of arbitrary fields which can be used in computed arguments.

Note

The Master Keybinding TOML file is a literate document. If you'd like to share your bindings with others, keep the following in mind: any comments on their own line that do not start with #- are interpreted as markdown when generating the textual documentation. All keybindings falling between two given sections of documentation text are converted into a single table. If you want the documentation to be clear, write up good comments in this binding file and group your bindings into logical sections between these comments.

Limitation

A current limitation of Master Key is that # comments on their own line cause the fields before and after the comment to be parsed separately. Use #- to avoid splitting a single object in two. There are plans to eliminate this limitation in the future

Here's a minimal example, demonstrating the most basic use of each field

toml
[header]
# this denotes the file-format version, it must be semver compatible with 2.0
version = "2.0"
name = "My Bindings"

[[mode]]
name = "insert"

[[mode]]
name = "normal"
default = true

[[kind]]
name = "motion"
description = "Commands that move your cursor"

[[kind]]
name = "mode"
description = "Commands that change the keybinding mode"

[[bind]]
key = "i"
name = "insert"
mode = "normal"
command = "master-key.enterInsert"
kind = "mode"

[[bind]]
key = "escape"
name = "normal"
mode = "insert"
command = "master-key.enterNormal"
kind = "mode"

[[default]]
id = "basic_motion"
name = "Motion Keys"
default.mode = "normal"
default.kind = "motion"
default.command = "cursorMove"

[[bind]]
name = "right"
defaults = "basic_motion"
key = "l"
args.to = "right"

[[bind]]
name = "left"
defaults = "basic_motion"
key = "h"
args.to = "left"

[define]
foo = 1

[[bind]]
name = "double right"
key = "g l"
defaults = "basic_motion"
args.to = "right"
computedArgs.value = "foo+1"