runtime/help/tutorial.md

   1 # Tutorial
   2
   3 This is a brief intro to micro's configuration system that will give some simple
   4 examples showing how to configure settings, rebind keys, and use `init.lua` to
   5 configure micro to your liking.
   6
   7 Hopefully you'll find this useful.
   8
   9 See `> help defaultkeys` for a list an explanation of the default keybindings.
  10
  11 ### Plugins
  12
  13 Micro has a plugin manager which can automatically download plugins for you. To
  14 see the 'official' plugins, go to github.com/micro-editor/plugin-channel.
  15
  16 For example, if you'd like to install the snippets plugin (listed in that repo),
  17 just press `CtrlE` to execute a command, and type `plugin install snippets`.
  18
  19 For more information about the plugin manager, see the end of the `plugins` help
  20 topic.
  21
  22 ### Settings
  23
  24 In micro, your settings are stored in `~/.config/micro/settings.json`, a file
  25 that is created the first time you run micro. It is a json file which holds all
  26 the settings and their values. To change an option, you can either change the
  27 value in the `settings.json` file, or you can type it in directly while using
  28 micro.
  29
  30 Simply press CtrlE to go to command mode, and type `set option value` (in the
  31 future, I will use `> set option value` to indicate pressing CtrlE). The change
  32 will take effect immediately and will also be saved to the `settings.json` file
  33 so that the setting will stick even after you close micro.
  34
  35 You can also set options locally which means that the setting will only have the
  36 value you give it in the buffer you set it in. For example, if you have two
  37 splits open, and you type `> setlocal tabsize 2`, the tabsize will only be 2 in
  38 the current buffer. Also micro will not save this local change to the
  39 `settings.json` file. However, you can still set options locally in the
  40 `settings.json` file. For example, if you want the `tabsize` to be 2 only in
  41 Ruby files, and 4 otherwise, you could put the following in `settings.json`:
  42
  43 ```json
  44 {
  45     "*.rb": {
  46         "tabsize": 2
  47     },
  48     "tabsize": 4
  49 }
  50 ```
  51
  52 Micro will set the `tabsize` to 2 only in files which match the glob `*.rb`.
  53
  54 If you would like to know more about all the available options, see the
  55 `options` topic (`> help options`).
  56
  57 ### Keybindings
  58
  59 Keybindings work in much the same way as options. You configure them using the
  60 `~/.config/micro/bindings.json` file.
  61
  62 For example if you would like to bind `CtrlR` to redo you could put the
  63 following in `bindings.json`:
  64
  65 ```json
  66 {
  67     "CtrlR": "redo"
  68 }
  69 ```
  70
  71 Very simple.
  72
  73 You can also bind keys while in micro by using the `> bind key action` command,
  74 but the bindings you make with the command won't be saved to the `bindings.json`
  75 file.
  76
  77 For more information about keybindings, like which keys can be bound, and
  78 what actions are available, see the `keybindings` help topic (`> help keybindings`).
  79
  80 ### Configuration with Lua
  81
  82 If you need more power than the json files provide, you can use the `init.lua`
  83 file. Create it in `~/.config/micro`. This file is a lua file that is run when
  84 micro starts and is essentially a one-file plugin.
  85
  86 I'll show you how to use the `init.lua` file by giving an example of how to
  87 create a binding to `CtrlR` which will execute `go run` on the current file,
  88 given that the current file is a Go file.
  89
  90 You can do that by putting the following in `init.lua`:
  91
  92 ```lua
  93 function gorun()
  94     local buf = CurView().Buf -- The current buffer
  95     if buf:FileType() == "go" then
  96         HandleShellCommand("go run " .. buf.Path, true, true) -- the first true means don't run it in the background
  97     end
  98 end
  99
 100 BindKey("CtrlR", "init.gorun")
 101 ```
 102
 103 Alternatively, you could get rid of the `BindKey` line, and put this line in the
 104 `bindings.json` file:
 105
 106 ```json
 107 {
 108     "CtrlR": "init.gorun"
 109 }
 110 ```
 111
 112 For more information about plugins and the lua system that micro uses, see the
 113 `plugins` help topic (`> help plugins`).